@ekaone/entropy 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eka Prasetia <ekaone3033@gmail.com> (https://prasetia.me)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @ekaone/entropy
+
+> Under Active Development, not release yet
+
+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](https://en.wikipedia.org/wiki/Entropy_(information_theory)) for details.
+
+## Installation
+
+```bash
+npm install @ekaone/entropy
+```
+
+```bash
+yarn add @ekaone/entropy
+```
+
+```bash
+pnpm add @ekaone/entropy
+```
+
+## Usage
+
+### Basic — pure measurement
+
+```ts
+import { calculate } from "@ekaone/entropy"
+
+calculate("hsg3-3;gs")
+// { entropy: 3.46, length: 9, unique: 8 }
+```
+
+### With `level` option
+
+```ts
+calculate("hsg3-3;gs", { level: true })
+// { entropy: 3.46, length: 9, unique: 8, level: "medium" }
+```
+
+### With `charset` option
+
+```ts
+calculate("hsg3-3;gs", { level: true, charset: true })
+// { entropy: 3.46, length: 9, unique: 8, level: "medium", charset: "mixed" }
+```
+
+### Custom thresholds
+
+```ts
+calculate("hsg3-3;gs", {
+  level: { thresholds: { high: 5.0 } }
+})
+```
+
+### Tree-shakeable primitives
+
+```ts
+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).
+
+### 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:
+
+```ts
+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](https://www.npmjs.com/package/@ekaone/entropy)
+- [GitHub Repository](https://github.com/ekaone/entropy)
+- [Issue Tracker](https://github.com/ekaone/entropy/issues)

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+type EntropyLevel = "low" | "medium" | "high" | "critical";
+type CharSet = "alpha" | "numeric" | "alphanumeric" | "hex" | "mixed";
+interface EntropyThresholds {
+    low: number;
+    medium: number;
+    high: number;
+}
+interface EntropyOptions {
+    level?: boolean | {
+        thresholds?: Partial<EntropyThresholds>;
+    };
+    charset?: boolean;
+}
+interface EntropyResult {
+    entropy: number;
+    length: number;
+    unique: number;
+    level?: EntropyLevel;
+    charset?: CharSet;
+}
+
+/**
+ * Calculates Shannon entropy of a string.
+ * Returns bits of entropy per character (0 to ~6.55 for printable ASCII).
+ *
+ * Best used for measuring randomness density of generated strings,
+ * tokens, secrets, and API keys — not human-chosen passwords.
+ *
+ * @see https://en.wikipedia.org/wiki/Entropy_(information_theory)
+ */
+declare function shannonEntropy(input: string): number;
+
+declare const DEFAULT_THRESHOLDS: EntropyThresholds;
+declare function classifyLevel(entropy: number, thresholds?: EntropyThresholds): EntropyLevel;
+declare function resolveThresholds(overrides?: Partial<EntropyThresholds>): EntropyThresholds;
+
+/**
+ * Detects the character set family of a string.
+ *
+ * Priority:
+ *  1. numeric      — digits only
+ *  2. alpha        — letters only (checked before hex to avoid "deadbeef" → hex)
+ *  3. hex          — hex chars [0-9a-fA-F] AND has both a digit and a letter AND no letters outside a-f range
+ *  4. alphanumeric — letters + digits, but NOT purely hex
+ *  5. mixed        — everything else (has special chars)
+ */
+declare function detectCharset(input: string): CharSet;
+
+/**
+ * index.ts
+ * @description Primitive Shannon entropy measurement for strings.
+ * @author Eka Prasetia
+ */
+
+declare function calculate(input: string, options?: EntropyOptions): EntropyResult;
+
+export { type CharSet, DEFAULT_THRESHOLDS, type EntropyLevel, type EntropyOptions, type EntropyResult, type EntropyThresholds, calculate, classifyLevel, detectCharset, resolveThresholds, shannonEntropy };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+type EntropyLevel = "low" | "medium" | "high" | "critical";
+type CharSet = "alpha" | "numeric" | "alphanumeric" | "hex" | "mixed";
+interface EntropyThresholds {
+    low: number;
+    medium: number;
+    high: number;
+}
+interface EntropyOptions {
+    level?: boolean | {
+        thresholds?: Partial<EntropyThresholds>;
+    };
+    charset?: boolean;
+}
+interface EntropyResult {
+    entropy: number;
+    length: number;
+    unique: number;
+    level?: EntropyLevel;
+    charset?: CharSet;
+}
+
+/**
+ * Calculates Shannon entropy of a string.
+ * Returns bits of entropy per character (0 to ~6.55 for printable ASCII).
+ *
+ * Best used for measuring randomness density of generated strings,
+ * tokens, secrets, and API keys — not human-chosen passwords.
+ *
+ * @see https://en.wikipedia.org/wiki/Entropy_(information_theory)
+ */
+declare function shannonEntropy(input: string): number;
+
+declare const DEFAULT_THRESHOLDS: EntropyThresholds;
+declare function classifyLevel(entropy: number, thresholds?: EntropyThresholds): EntropyLevel;
+declare function resolveThresholds(overrides?: Partial<EntropyThresholds>): EntropyThresholds;
+
+/**
+ * Detects the character set family of a string.
+ *
+ * Priority:
+ *  1. numeric      — digits only
+ *  2. alpha        — letters only (checked before hex to avoid "deadbeef" → hex)
+ *  3. hex          — hex chars [0-9a-fA-F] AND has both a digit and a letter AND no letters outside a-f range
+ *  4. alphanumeric — letters + digits, but NOT purely hex
+ *  5. mixed        — everything else (has special chars)
+ */
+declare function detectCharset(input: string): CharSet;
+
+/**
+ * index.ts
+ * @description Primitive Shannon entropy measurement for strings.
+ * @author Eka Prasetia
+ */
+
+declare function calculate(input: string, options?: EntropyOptions): EntropyResult;
+
+export { type CharSet, DEFAULT_THRESHOLDS, type EntropyLevel, type EntropyOptions, type EntropyResult, type EntropyThresholds, calculate, classifyLevel, detectCharset, resolveThresholds, shannonEntropy };

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";var y=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var E=Object.prototype.hasOwnProperty;var i=(e,t)=>{for(var o in t)y(e,o,{get:t[o],enumerable:!0})},d=(e,t,o,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of u(t))!E.call(e,r)&&r!==o&&y(e,r,{get:()=>t[r],enumerable:!(n=p(t,r))||n.enumerable});return e};var L=e=>d(y({},"__esModule",{value:!0}),e);var O={};i(O,{DEFAULT_THRESHOLDS:()=>h,calculate:()=>_,classifyLevel:()=>c,detectCharset:()=>a,resolveThresholds:()=>f,shannonEntropy:()=>l});module.exports=L(O);function l(e){var r;if(e.length===0)return 0;let t=new Map;for(let s of e)t.set(s,((r=t.get(s))!=null?r:0)+1);let o=e.length,n=0;for(let s of t.values()){let m=s/o;n-=m*Math.log2(m)}return Math.round(n*1e3)/1e3}var h={low:2.5,medium:3.5,high:4.5};function c(e,t=h){return e<t.low?"low":e<t.medium?"medium":e<t.high?"high":"critical"}function f(e){return{...h,...e}}var T=/^[0-9]+$/,g=/^[a-zA-Z]+$/,A=/^[0-9a-fA-F]+$/,v=/^[a-zA-Z0-9]+$/,x=/[0-9]/,H=/[a-zA-Z]/,S=/[g-zG-Z]/;function a(e){return e.length===0?"mixed":T.test(e)?"numeric":g.test(e)?"alpha":A.test(e)&&x.test(e)&&H.test(e)&&!S.test(e)?"hex":v.test(e)?"alphanumeric":"mixed"}function _(e,t){let o=l(e),n={entropy:o,length:e.length,unique:new Set(e).size};if(t!=null&&t.level){let r=f(typeof t.level=="object"?t.level.thresholds:void 0);n.level=c(o,r)}return t!=null&&t.charset&&(n.charset=a(e)),n}0&&(module.exports={DEFAULT_THRESHOLDS,calculate,classifyLevel,detectCharset,resolveThresholds,shannonEntropy});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/calculate.ts","../src/level.ts","../src/charset.ts"],"sourcesContent":["/**\n * index.ts\n * @description Primitive Shannon entropy measurement for strings.\n * @author Eka Prasetia\n */\n\nimport { shannonEntropy } from \"./calculate\";\nimport { classifyLevel, resolveThresholds } from \"./level\";\nimport { detectCharset } from \"./charset\";\nimport type { EntropyOptions, EntropyResult } from \"./types\";\n\nexport function calculate(\n  input: string,\n  options?: EntropyOptions,\n): EntropyResult {\n  const entropy = shannonEntropy(input);\n\n  const result: EntropyResult = {\n    entropy,\n    length: input.length,\n    unique: new Set(input).size,\n  };\n\n  if (options?.level) {\n    const thresholds = resolveThresholds(\n      typeof options.level === \"object\" ? options.level.thresholds : undefined,\n    );\n    result.level = classifyLevel(entropy, thresholds);\n  }\n\n  if (options?.charset) {\n    result.charset = detectCharset(input);\n  }\n\n  return result;\n}\n\n// named exports for tree-shaking\nexport { shannonEntropy } from \"./calculate\";\nexport { classifyLevel, resolveThresholds, DEFAULT_THRESHOLDS } from \"./level\";\nexport { detectCharset } from \"./charset\";\nexport type {\n  EntropyOptions,\n  EntropyResult,\n  EntropyLevel,\n  CharSet,\n  EntropyThresholds,\n} from \"./types\";\n","/**\r\n * Calculates Shannon entropy of a string.\r\n * Returns bits of entropy per character (0 to ~6.55 for printable ASCII).\r\n *\r\n * Best used for measuring randomness density of generated strings,\r\n * tokens, secrets, and API keys — not human-chosen passwords.\r\n *\r\n * @see https://en.wikipedia.org/wiki/Entropy_(information_theory)\r\n */\r\nexport function shannonEntropy(input: string): number {\r\n  if (input.length === 0) return 0;\r\n\r\n  const freq = new Map<string, number>();\r\n\r\n  for (const char of input) {\r\n    freq.set(char, (freq.get(char) ?? 0) + 1);\r\n  }\r\n\r\n  const len = input.length;\r\n  let entropy = 0;\r\n\r\n  for (const count of freq.values()) {\r\n    const p = count / len;\r\n    entropy -= p * Math.log2(p);\r\n  }\r\n\r\n  return Math.round(entropy * 1000) / 1000; // 3 decimal precision\r\n}\r\n","import type { EntropyLevel, EntropyThresholds } from \"./types\";\r\n\r\nexport const DEFAULT_THRESHOLDS: EntropyThresholds = {\r\n  low: 2.5,\r\n  medium: 3.5,\r\n  high: 4.5,\r\n  // above 4.5 → \"critical\"\r\n};\r\n\r\nexport function classifyLevel(\r\n  entropy: number,\r\n  thresholds: EntropyThresholds = DEFAULT_THRESHOLDS,\r\n): EntropyLevel {\r\n  if (entropy < thresholds.low) return \"low\";\r\n  if (entropy < thresholds.medium) return \"medium\";\r\n  if (entropy < thresholds.high) return \"high\";\r\n  return \"critical\";\r\n}\r\n\r\nexport function resolveThresholds(\r\n  overrides?: Partial<EntropyThresholds>,\r\n): EntropyThresholds {\r\n  return { ...DEFAULT_THRESHOLDS, ...overrides };\r\n}\r\n","import type { CharSet } from \"./types\";\r\n\r\nconst ONLY_DIGITS = /^[0-9]+$/;\r\nconst ONLY_ALPHA = /^[a-zA-Z]+$/;\r\nconst ONLY_HEX = /^[0-9a-fA-F]+$/;\r\nconst ONLY_ALPHANUM = /^[a-zA-Z0-9]+$/;\r\nconst HAS_DIGIT = /[0-9]/;\r\nconst HAS_ALPHA = /[a-zA-Z]/;\r\nconst HAS_NON_HEX_LETTER = /[g-zG-Z]/; // letters outside hex range\r\n\r\n/**\r\n * Detects the character set family of a string.\r\n *\r\n * Priority:\r\n *  1. numeric      — digits only\r\n *  2. alpha        — letters only (checked before hex to avoid \"deadbeef\" → hex)\r\n *  3. hex          — hex chars [0-9a-fA-F] AND has both a digit and a letter AND no letters outside a-f range\r\n *  4. alphanumeric — letters + digits, but NOT purely hex\r\n *  5. mixed        — everything else (has special chars)\r\n */\r\nexport function detectCharset(input: string): CharSet {\r\n  if (input.length === 0) return \"mixed\";\r\n\r\n  if (ONLY_DIGITS.test(input)) return \"numeric\";\r\n  if (ONLY_ALPHA.test(input)) return \"alpha\";\r\n\r\n  // hex: must match hex pattern AND have both digits and letters AND no letters outside a-f range\r\n  if (\r\n    ONLY_HEX.test(input) &&\r\n    HAS_DIGIT.test(input) &&\r\n    HAS_ALPHA.test(input) &&\r\n    !HAS_NON_HEX_LETTER.test(input)\r\n  )\r\n    return \"hex\";\r\n\r\n  if (ONLY_ALPHANUM.test(input)) return \"alphanumeric\";\r\n\r\n  return \"mixed\";\r\n}\r\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,wBAAAE,EAAA,cAAAC,EAAA,kBAAAC,EAAA,kBAAAC,EAAA,sBAAAC,EAAA,mBAAAC,IAAA,eAAAC,EAAAR,GCSO,SAASS,EAAeC,EAAuB,CATtD,IAAAC,EAUE,GAAID,EAAM,SAAW,EAAG,MAAO,GAE/B,IAAME,EAAO,IAAI,IAEjB,QAAWC,KAAQH,EACjBE,EAAK,IAAIC,IAAOF,EAAAC,EAAK,IAAIC,CAAI,IAAb,KAAAF,EAAkB,GAAK,CAAC,EAG1C,IAAMG,EAAMJ,EAAM,OACdK,EAAU,EAEd,QAAWC,KAASJ,EAAK,OAAO,EAAG,CACjC,IAAMK,EAAID,EAAQF,EAClBC,GAAWE,EAAI,KAAK,KAAKA,CAAC,CAC5B,CAEA,OAAO,KAAK,MAAMF,EAAU,GAAI,EAAI,GACtC,CCzBO,IAAMG,EAAwC,CACnD,IAAK,IACL,OAAQ,IACR,KAAM,GAER,EAEO,SAASC,EACdC,EACAC,EAAgCH,EAClB,CACd,OAAIE,EAAUC,EAAW,IAAY,MACjCD,EAAUC,EAAW,OAAe,SACpCD,EAAUC,EAAW,KAAa,OAC/B,UACT,CAEO,SAASC,EACdC,EACmB,CACnB,MAAO,CAAE,GAAGL,EAAoB,GAAGK,CAAU,CAC/C,CCrBA,IAAMC,EAAc,WACdC,EAAa,cACbC,EAAW,iBACXC,EAAgB,iBAChBC,EAAY,QACZC,EAAY,WACZC,EAAqB,WAYpB,SAASC,EAAcC,EAAwB,CACpD,OAAIA,EAAM,SAAW,EAAU,QAE3BR,EAAY,KAAKQ,CAAK,EAAU,UAChCP,EAAW,KAAKO,CAAK,EAAU,QAIjCN,EAAS,KAAKM,CAAK,GACnBJ,EAAU,KAAKI,CAAK,GACpBH,EAAU,KAAKG,CAAK,GACpB,CAACF,EAAmB,KAAKE,CAAK,EAEvB,MAELL,EAAc,KAAKK,CAAK,EAAU,eAE/B,OACT,CH3BO,SAASC,EACdC,EACAC,EACe,CACf,IAAMC,EAAUC,EAAeH,CAAK,EAE9BI,EAAwB,CAC5B,QAAAF,EACA,OAAQF,EAAM,OACd,OAAQ,IAAI,IAAIA,CAAK,EAAE,IACzB,EAEA,GAAIC,GAAA,MAAAA,EAAS,MAAO,CAClB,IAAMI,EAAaC,EACjB,OAAOL,EAAQ,OAAU,SAAWA,EAAQ,MAAM,WAAa,MACjE,EACAG,EAAO,MAAQG,EAAcL,EAASG,CAAU,CAClD,CAEA,OAAIJ,GAAA,MAAAA,EAAS,UACXG,EAAO,QAAUI,EAAcR,CAAK,GAG/BI,CACT","names":["index_exports","__export","DEFAULT_THRESHOLDS","calculate","classifyLevel","detectCharset","resolveThresholds","shannonEntropy","__toCommonJS","shannonEntropy","input","_a","freq","char","len","entropy","count","p","DEFAULT_THRESHOLDS","classifyLevel","entropy","thresholds","resolveThresholds","overrides","ONLY_DIGITS","ONLY_ALPHA","ONLY_HEX","ONLY_ALPHANUM","HAS_DIGIT","HAS_ALPHA","HAS_NON_HEX_LETTER","detectCharset","input","calculate","input","options","entropy","shannonEntropy","result","thresholds","resolveThresholds","classifyLevel","detectCharset"]}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+function l(e){var n;if(e.length===0)return 0;let t=new Map;for(let s of e)t.set(s,((n=t.get(s))!=null?n:0)+1);let o=e.length,r=0;for(let s of t.values()){let y=s/o;r-=y*Math.log2(y)}return Math.round(r*1e3)/1e3}var h={low:2.5,medium:3.5,high:4.5};function c(e,t=h){return e<t.low?"low":e<t.medium?"medium":e<t.high?"high":"critical"}function f(e){return{...h,...e}}var m=/^[0-9]+$/,p=/^[a-zA-Z]+$/,u=/^[0-9a-fA-F]+$/,E=/^[a-zA-Z0-9]+$/,i=/[0-9]/,d=/[a-zA-Z]/,L=/[g-zG-Z]/;function a(e){return e.length===0?"mixed":m.test(e)?"numeric":p.test(e)?"alpha":u.test(e)&&i.test(e)&&d.test(e)&&!L.test(e)?"hex":E.test(e)?"alphanumeric":"mixed"}function S(e,t){let o=l(e),r={entropy:o,length:e.length,unique:new Set(e).size};if(t!=null&&t.level){let n=f(typeof t.level=="object"?t.level.thresholds:void 0);r.level=c(o,n)}return t!=null&&t.charset&&(r.charset=a(e)),r}export{h as DEFAULT_THRESHOLDS,S as calculate,c as classifyLevel,a as detectCharset,f as resolveThresholds,l as shannonEntropy};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/calculate.ts","../src/level.ts","../src/charset.ts","../src/index.ts"],"sourcesContent":["/**\r\n * Calculates Shannon entropy of a string.\r\n * Returns bits of entropy per character (0 to ~6.55 for printable ASCII).\r\n *\r\n * Best used for measuring randomness density of generated strings,\r\n * tokens, secrets, and API keys — not human-chosen passwords.\r\n *\r\n * @see https://en.wikipedia.org/wiki/Entropy_(information_theory)\r\n */\r\nexport function shannonEntropy(input: string): number {\r\n  if (input.length === 0) return 0;\r\n\r\n  const freq = new Map<string, number>();\r\n\r\n  for (const char of input) {\r\n    freq.set(char, (freq.get(char) ?? 0) + 1);\r\n  }\r\n\r\n  const len = input.length;\r\n  let entropy = 0;\r\n\r\n  for (const count of freq.values()) {\r\n    const p = count / len;\r\n    entropy -= p * Math.log2(p);\r\n  }\r\n\r\n  return Math.round(entropy * 1000) / 1000; // 3 decimal precision\r\n}\r\n","import type { EntropyLevel, EntropyThresholds } from \"./types\";\r\n\r\nexport const DEFAULT_THRESHOLDS: EntropyThresholds = {\r\n  low: 2.5,\r\n  medium: 3.5,\r\n  high: 4.5,\r\n  // above 4.5 → \"critical\"\r\n};\r\n\r\nexport function classifyLevel(\r\n  entropy: number,\r\n  thresholds: EntropyThresholds = DEFAULT_THRESHOLDS,\r\n): EntropyLevel {\r\n  if (entropy < thresholds.low) return \"low\";\r\n  if (entropy < thresholds.medium) return \"medium\";\r\n  if (entropy < thresholds.high) return \"high\";\r\n  return \"critical\";\r\n}\r\n\r\nexport function resolveThresholds(\r\n  overrides?: Partial<EntropyThresholds>,\r\n): EntropyThresholds {\r\n  return { ...DEFAULT_THRESHOLDS, ...overrides };\r\n}\r\n","import type { CharSet } from \"./types\";\r\n\r\nconst ONLY_DIGITS = /^[0-9]+$/;\r\nconst ONLY_ALPHA = /^[a-zA-Z]+$/;\r\nconst ONLY_HEX = /^[0-9a-fA-F]+$/;\r\nconst ONLY_ALPHANUM = /^[a-zA-Z0-9]+$/;\r\nconst HAS_DIGIT = /[0-9]/;\r\nconst HAS_ALPHA = /[a-zA-Z]/;\r\nconst HAS_NON_HEX_LETTER = /[g-zG-Z]/; // letters outside hex range\r\n\r\n/**\r\n * Detects the character set family of a string.\r\n *\r\n * Priority:\r\n *  1. numeric      — digits only\r\n *  2. alpha        — letters only (checked before hex to avoid \"deadbeef\" → hex)\r\n *  3. hex          — hex chars [0-9a-fA-F] AND has both a digit and a letter AND no letters outside a-f range\r\n *  4. alphanumeric — letters + digits, but NOT purely hex\r\n *  5. mixed        — everything else (has special chars)\r\n */\r\nexport function detectCharset(input: string): CharSet {\r\n  if (input.length === 0) return \"mixed\";\r\n\r\n  if (ONLY_DIGITS.test(input)) return \"numeric\";\r\n  if (ONLY_ALPHA.test(input)) return \"alpha\";\r\n\r\n  // hex: must match hex pattern AND have both digits and letters AND no letters outside a-f range\r\n  if (\r\n    ONLY_HEX.test(input) &&\r\n    HAS_DIGIT.test(input) &&\r\n    HAS_ALPHA.test(input) &&\r\n    !HAS_NON_HEX_LETTER.test(input)\r\n  )\r\n    return \"hex\";\r\n\r\n  if (ONLY_ALPHANUM.test(input)) return \"alphanumeric\";\r\n\r\n  return \"mixed\";\r\n}\r\n","/**\n * index.ts\n * @description Primitive Shannon entropy measurement for strings.\n * @author Eka Prasetia\n */\n\nimport { shannonEntropy } from \"./calculate\";\nimport { classifyLevel, resolveThresholds } from \"./level\";\nimport { detectCharset } from \"./charset\";\nimport type { EntropyOptions, EntropyResult } from \"./types\";\n\nexport function calculate(\n  input: string,\n  options?: EntropyOptions,\n): EntropyResult {\n  const entropy = shannonEntropy(input);\n\n  const result: EntropyResult = {\n    entropy,\n    length: input.length,\n    unique: new Set(input).size,\n  };\n\n  if (options?.level) {\n    const thresholds = resolveThresholds(\n      typeof options.level === \"object\" ? options.level.thresholds : undefined,\n    );\n    result.level = classifyLevel(entropy, thresholds);\n  }\n\n  if (options?.charset) {\n    result.charset = detectCharset(input);\n  }\n\n  return result;\n}\n\n// named exports for tree-shaking\nexport { shannonEntropy } from \"./calculate\";\nexport { classifyLevel, resolveThresholds, DEFAULT_THRESHOLDS } from \"./level\";\nexport { detectCharset } from \"./charset\";\nexport type {\n  EntropyOptions,\n  EntropyResult,\n  EntropyLevel,\n  CharSet,\n  EntropyThresholds,\n} from \"./types\";\n"],"mappings":"AASO,SAASA,EAAeC,EAAuB,CATtD,IAAAC,EAUE,GAAID,EAAM,SAAW,EAAG,MAAO,GAE/B,IAAME,EAAO,IAAI,IAEjB,QAAWC,KAAQH,EACjBE,EAAK,IAAIC,IAAOF,EAAAC,EAAK,IAAIC,CAAI,IAAb,KAAAF,EAAkB,GAAK,CAAC,EAG1C,IAAMG,EAAMJ,EAAM,OACdK,EAAU,EAEd,QAAWC,KAASJ,EAAK,OAAO,EAAG,CACjC,IAAMK,EAAID,EAAQF,EAClBC,GAAWE,EAAI,KAAK,KAAKA,CAAC,CAC5B,CAEA,OAAO,KAAK,MAAMF,EAAU,GAAI,EAAI,GACtC,CCzBO,IAAMG,EAAwC,CACnD,IAAK,IACL,OAAQ,IACR,KAAM,GAER,EAEO,SAASC,EACdC,EACAC,EAAgCH,EAClB,CACd,OAAIE,EAAUC,EAAW,IAAY,MACjCD,EAAUC,EAAW,OAAe,SACpCD,EAAUC,EAAW,KAAa,OAC/B,UACT,CAEO,SAASC,EACdC,EACmB,CACnB,MAAO,CAAE,GAAGL,EAAoB,GAAGK,CAAU,CAC/C,CCrBA,IAAMC,EAAc,WACdC,EAAa,cACbC,EAAW,iBACXC,EAAgB,iBAChBC,EAAY,QACZC,EAAY,WACZC,EAAqB,WAYpB,SAASC,EAAcC,EAAwB,CACpD,OAAIA,EAAM,SAAW,EAAU,QAE3BR,EAAY,KAAKQ,CAAK,EAAU,UAChCP,EAAW,KAAKO,CAAK,EAAU,QAIjCN,EAAS,KAAKM,CAAK,GACnBJ,EAAU,KAAKI,CAAK,GACpBH,EAAU,KAAKG,CAAK,GACpB,CAACF,EAAmB,KAAKE,CAAK,EAEvB,MAELL,EAAc,KAAKK,CAAK,EAAU,eAE/B,OACT,CC3BO,SAASC,EACdC,EACAC,EACe,CACf,IAAMC,EAAUC,EAAeH,CAAK,EAE9BI,EAAwB,CAC5B,QAAAF,EACA,OAAQF,EAAM,OACd,OAAQ,IAAI,IAAIA,CAAK,EAAE,IACzB,EAEA,GAAIC,GAAA,MAAAA,EAAS,MAAO,CAClB,IAAMI,EAAaC,EACjB,OAAOL,EAAQ,OAAU,SAAWA,EAAQ,MAAM,WAAa,MACjE,EACAG,EAAO,MAAQG,EAAcL,EAASG,CAAU,CAClD,CAEA,OAAIJ,GAAA,MAAAA,EAAS,UACXG,EAAO,QAAUI,EAAcR,CAAK,GAG/BI,CACT","names":["shannonEntropy","input","_a","freq","char","len","entropy","count","p","DEFAULT_THRESHOLDS","classifyLevel","entropy","thresholds","resolveThresholds","overrides","ONLY_DIGITS","ONLY_ALPHA","ONLY_HEX","ONLY_ALPHANUM","HAS_DIGIT","HAS_ALPHA","HAS_NON_HEX_LETTER","detectCharset","input","calculate","input","options","entropy","shannonEntropy","result","thresholds","resolveThresholds","classifyLevel","detectCharset"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@ekaone/entropy",
+  "version": "0.0.1",
+  "description": "Primitive Shannon entropy measurement for strings.",
+  "keywords": [
+    "typescript",
+    "library",
+    "privacy",
+    "security",
+    "entropy",
+    "randomness",
+    "density"
+  ],
+  "author": {
+    "name": "Eka Prasetia",
+    "email": "ekaone3033@gmail.com",
+    "url": "https://prasetia.me"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekaone/entropy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ekaone/entropy/issues"
+  },
+  "homepage": "https://github.com/ekaone/entropy#readme",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}