@envind/ts-enum-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cuzeac Florin
+
+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,135 @@
+# ts-enum-utils
+
+[![npm version](https://img.shields.io/npm/v/ts-enum-utils.svg)](https://www.npmjs.com/package/ts-enum-utils)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/ts-enum-utils)](https://bundlephobia.com/package/ts-enum-utils)
+
+Type-safe runtime enums with built-in utilities for TypeScript.
+
+## Why?
+
+TypeScript's native enums have issues:
+
+- Not iterable without hacks
+- Weird reverse mapping behavior
+- No built-in validation
+
+This library gives you **type-safe enums** with **runtime utilities** in ~30 lines.
+
+## Installation
+
+```bash
+npm install ts-enum-utils
+# or
+pnpm add ts-enum-utils
+# or
+yarn add ts-enum-utils
+```
+
+## Usage
+
+```typescript
+import { createEnum, type EnumValue } from "ts-enum-utils";
+
+const Status = createEnum(["pending", "active", "archived"] as const);
+
+// Direct value access (with autocomplete)
+Status.pending; // "pending"
+Status.active; // "active"
+Status.archived; // "archived"
+
+// Get all values
+Status.values; // ["pending", "active", "archived"]
+```
+
+### Type Guard
+
+```typescript
+const userInput: unknown = "pending";
+
+if (Status.is(userInput)) {
+  // userInput is now typed as "pending" | "active" | "archived"
+  console.log(userInput);
+}
+```
+
+### Validation with Error
+
+```typescript
+// Throws if invalid
+const validated = Status.assert(untrustedData);
+// Returns the value if valid, throws otherwise
+```
+
+### Extract the Type
+
+```typescript
+type Status = EnumValue<typeof Status>;
+// "pending" | "active" | "archived"
+
+const updateStatus = (id: string, status: Status) => {
+  // ...
+};
+```
+
+### Utilities
+
+```typescript
+// Random value (great for tests/mocks)
+Status.random(); // "pending" | "active" | "archived"
+
+// Get index
+Status.indexOf("active"); // 1
+
+// Get by index (supports negative)
+Status.at(0); // "pending"
+Status.at(-1); // "archived"
+```
+
+## API
+
+### `createEnum(values)`
+
+Creates a type-safe enum object.
+
+| Method            | Description                                |
+| ----------------- | ------------------------------------------ |
+| `.values`         | Readonly array of all enum values          |
+| `.is(value)`      | Type guard that checks if value is valid   |
+| `.assert(value)`  | Returns value if valid, throws otherwise   |
+| `.random()`       | Returns a random enum value                |
+| `.indexOf(value)` | Returns the index of a value               |
+| `.at(index)`      | Returns value at index (supports negative) |
+
+### `EnumValue<E>`
+
+Utility type to extract the union type from an enum.
+
+```typescript
+type Status = EnumValue<typeof Status>;
+// "pending" | "active" | "archived"
+```
+
+## Comparison
+
+| Feature     | Native Enum | ts-enum-utils  |
+| ----------- | ----------- | -------------- |
+| Type-safe   | ✅          | ✅             |
+| Iterable    | ❌          | ✅ `.values`   |
+| Type guard  | ❌          | ✅ `.is()`     |
+| Validation  | ❌          | ✅ `.assert()` |
+| Random      | ❌          | ✅ `.random()` |
+| Bundle size | -           | ~500B          |
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+<div align="center">
+
+**[⭐ Star us on GitHub](https://github.com/envindavsorg/ts-enum-utils)** • **[📦 NPM Package](https://www.npmjs.com/package/ts-enum-utils)** • **[📚 Documentation](https://github.com/envindavsorg/ts-enum-utils#readme)**
+
+Made with ❤️ by Cuzeac Florin in Paris.
+
+</div>

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var s=e=>{if(e.length===0)throw new Error("Enum must have at least one value");if(new Set(e).size!==e.length)throw new Error("Enum values must be unique");let r=new Set(e),t={values:e,is:n=>typeof n=="string"&&r.has(n),assert:n=>{if(typeof n=="string"&&r.has(n))return n;throw new Error(`Invalid enum value: "${n}". Expected one of: ${e.join(", ")}`)},random:()=>{let n=Math.floor(Math.random()*e.length);return e[n]},indexOf:n=>e.indexOf(n),at:n=>e.at(n)},u=Object.fromEntries(e.map(n=>[n,n]));return Object.freeze({...t,...u})};exports.createEnum=s;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createEnum","values","valueSet","base","value","index","members","v"],"mappings":"aAiBO,IAAMA,CAAAA,CAAiDC,CAAAA,EAAuB,CACnF,GAAIA,CAAAA,CAAO,MAAA,GAAW,CAAA,CACpB,MAAM,IAAI,KAAA,CAAM,mCAAmC,CAAA,CAIrD,GADqB,IAAI,GAAA,CAAIA,CAAM,CAAA,CAClB,IAAA,GAASA,CAAAA,CAAO,MAAA,CAC/B,MAAM,IAAI,KAAA,CAAM,4BAA4B,CAAA,CAG9C,IAAMC,CAAAA,CAAW,IAAI,GAAA,CAAYD,CAAM,CAAA,CAEjCE,CAAAA,CAAoB,CACxB,MAAA,CAAAF,CAAAA,CAEA,EAAA,CAAKG,CAAAA,EAAuC,OAAOA,CAAAA,EAAU,QAAA,EAAYF,CAAAA,CAAS,GAAA,CAAIE,CAAK,CAAA,CAE3F,MAAA,CAASA,CAAAA,EAA8B,CACrC,GAAI,OAAOA,CAAAA,EAAU,QAAA,EAAYF,CAAAA,CAAS,GAAA,CAAIE,CAAK,CAAA,CACjD,OAAOA,CAAAA,CAET,MAAM,IAAI,KAAA,CAAM,CAAA,qBAAA,EAAwBA,CAAK,CAAA,oBAAA,EAAuBH,CAAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,CAAE,CACzF,CAAA,CAEA,MAAA,CAAQ,IAAiB,CACvB,IAAMI,CAAAA,CAAQ,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,MAAA,EAAO,CAAIJ,CAAAA,CAAO,MAAM,CAAA,CACtD,OAAOA,CAAAA,CAAOI,CAAK,CACrB,CAAA,CAEA,OAAA,CAAUD,CAAAA,EAA6BH,CAAAA,CAAO,OAAA,CAAQG,CAAK,CAAA,CAE3D,EAAA,CAAKC,CAAAA,EAAyCJ,CAAAA,CAAO,EAAA,CAAGI,CAAK,CAC/D,CAAA,CAEMC,CAAAA,CAAU,MAAA,CAAO,WAAA,CAAYL,CAAAA,CAAO,GAAA,CAAKM,CAAAA,EAAM,CAACA,CAAAA,CAAGA,CAAC,CAAC,CAAC,CAAA,CAE5D,OAAO,MAAA,CAAO,MAAA,CAAO,CAAE,GAAGJ,CAAAA,CAAM,GAAGG,CAAQ,CAAC,CAC9C","file":"index.cjs","sourcesContent":["type EnumBase<T extends readonly string[]> = {\n  readonly values: T;\n  is: (value: unknown) => value is T[number];\n  assert: (value: unknown) => T[number];\n  random: () => T[number];\n  indexOf: (value: T[number]) => number;\n  at: (index: number) => T[number] | undefined;\n};\n\ntype EnumMembers<T extends readonly string[]> = {\n  readonly [K in T[number]]: K;\n};\n\nexport type Enum<T extends readonly string[]> = EnumBase<T> & EnumMembers<T>;\n\nexport type EnumValue<E extends { values: readonly string[] }> = E[\"values\"][number];\n\nexport const createEnum = <const T extends readonly string[]>(values: T): Enum<T> => {\n  if (values.length === 0) {\n    throw new Error(\"Enum must have at least one value\");\n  }\n\n  const uniqueValues = new Set(values);\n  if (uniqueValues.size !== values.length) {\n    throw new Error(\"Enum values must be unique\");\n  }\n\n  const valueSet = new Set<string>(values);\n\n  const base: EnumBase<T> = {\n    values,\n\n    is: (value: unknown): value is T[number] => typeof value === \"string\" && valueSet.has(value),\n\n    assert: (value: unknown): T[number] => {\n      if (typeof value === \"string\" && valueSet.has(value)) {\n        return value as T[number];\n      }\n      throw new Error(`Invalid enum value: \"${value}\". Expected one of: ${values.join(\", \")}`);\n    },\n\n    random: (): T[number] => {\n      const index = Math.floor(Math.random() * values.length);\n      return values[index] as T[number];\n    },\n\n    indexOf: (value: T[number]): number => values.indexOf(value),\n\n    at: (index: number): T[number] | undefined => values.at(index) as T[number] | undefined,\n  };\n\n  const members = Object.fromEntries(values.map((v) => [v, v])) as EnumMembers<T>;\n\n  return Object.freeze({ ...base, ...members }) as Enum<T>;\n};\n"]}

package/dist/index.d.cts

@@ -0,0 +1,18 @@
+type EnumBase<T extends readonly string[]> = {
+    readonly values: T;
+    is: (value: unknown) => value is T[number];
+    assert: (value: unknown) => T[number];
+    random: () => T[number];
+    indexOf: (value: T[number]) => number;
+    at: (index: number) => T[number] | undefined;
+};
+type EnumMembers<T extends readonly string[]> = {
+    readonly [K in T[number]]: K;
+};
+type Enum<T extends readonly string[]> = EnumBase<T> & EnumMembers<T>;
+type EnumValue<E extends {
+    values: readonly string[];
+}> = E["values"][number];
+declare const createEnum: <const T extends readonly string[]>(values: T) => Enum<T>;
+
+export { type Enum, type EnumValue, createEnum };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+type EnumBase<T extends readonly string[]> = {
+    readonly values: T;
+    is: (value: unknown) => value is T[number];
+    assert: (value: unknown) => T[number];
+    random: () => T[number];
+    indexOf: (value: T[number]) => number;
+    at: (index: number) => T[number] | undefined;
+};
+type EnumMembers<T extends readonly string[]> = {
+    readonly [K in T[number]]: K;
+};
+type Enum<T extends readonly string[]> = EnumBase<T> & EnumMembers<T>;
+type EnumValue<E extends {
+    values: readonly string[];
+}> = E["values"][number];
+declare const createEnum: <const T extends readonly string[]>(values: T) => Enum<T>;
+
+export { type Enum, type EnumValue, createEnum };

package/dist/index.js

@@ -0,0 +1,2 @@
+var s=e=>{if(e.length===0)throw new Error("Enum must have at least one value");if(new Set(e).size!==e.length)throw new Error("Enum values must be unique");let r=new Set(e),t={values:e,is:n=>typeof n=="string"&&r.has(n),assert:n=>{if(typeof n=="string"&&r.has(n))return n;throw new Error(`Invalid enum value: "${n}". Expected one of: ${e.join(", ")}`)},random:()=>{let n=Math.floor(Math.random()*e.length);return e[n]},indexOf:n=>e.indexOf(n),at:n=>e.at(n)},u=Object.fromEntries(e.map(n=>[n,n]));return Object.freeze({...t,...u})};export{s as createEnum};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createEnum","values","valueSet","base","value","index","members","v"],"mappings":"AAiBO,IAAMA,CAAAA,CAAiDC,CAAAA,EAAuB,CACnF,GAAIA,CAAAA,CAAO,MAAA,GAAW,CAAA,CACpB,MAAM,IAAI,KAAA,CAAM,mCAAmC,CAAA,CAIrD,GADqB,IAAI,GAAA,CAAIA,CAAM,CAAA,CAClB,IAAA,GAASA,CAAAA,CAAO,MAAA,CAC/B,MAAM,IAAI,KAAA,CAAM,4BAA4B,CAAA,CAG9C,IAAMC,CAAAA,CAAW,IAAI,GAAA,CAAYD,CAAM,CAAA,CAEjCE,CAAAA,CAAoB,CACxB,MAAA,CAAAF,CAAAA,CAEA,EAAA,CAAKG,CAAAA,EAAuC,OAAOA,CAAAA,EAAU,QAAA,EAAYF,CAAAA,CAAS,GAAA,CAAIE,CAAK,CAAA,CAE3F,MAAA,CAASA,CAAAA,EAA8B,CACrC,GAAI,OAAOA,CAAAA,EAAU,QAAA,EAAYF,CAAAA,CAAS,GAAA,CAAIE,CAAK,CAAA,CACjD,OAAOA,CAAAA,CAET,MAAM,IAAI,KAAA,CAAM,CAAA,qBAAA,EAAwBA,CAAK,CAAA,oBAAA,EAAuBH,CAAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,CAAE,CACzF,CAAA,CAEA,MAAA,CAAQ,IAAiB,CACvB,IAAMI,CAAAA,CAAQ,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,MAAA,EAAO,CAAIJ,CAAAA,CAAO,MAAM,CAAA,CACtD,OAAOA,CAAAA,CAAOI,CAAK,CACrB,CAAA,CAEA,OAAA,CAAUD,CAAAA,EAA6BH,CAAAA,CAAO,OAAA,CAAQG,CAAK,CAAA,CAE3D,EAAA,CAAKC,CAAAA,EAAyCJ,CAAAA,CAAO,EAAA,CAAGI,CAAK,CAC/D,CAAA,CAEMC,CAAAA,CAAU,MAAA,CAAO,WAAA,CAAYL,CAAAA,CAAO,GAAA,CAAKM,CAAAA,EAAM,CAACA,CAAAA,CAAGA,CAAC,CAAC,CAAC,CAAA,CAE5D,OAAO,MAAA,CAAO,MAAA,CAAO,CAAE,GAAGJ,CAAAA,CAAM,GAAGG,CAAQ,CAAC,CAC9C","file":"index.js","sourcesContent":["type EnumBase<T extends readonly string[]> = {\n  readonly values: T;\n  is: (value: unknown) => value is T[number];\n  assert: (value: unknown) => T[number];\n  random: () => T[number];\n  indexOf: (value: T[number]) => number;\n  at: (index: number) => T[number] | undefined;\n};\n\ntype EnumMembers<T extends readonly string[]> = {\n  readonly [K in T[number]]: K;\n};\n\nexport type Enum<T extends readonly string[]> = EnumBase<T> & EnumMembers<T>;\n\nexport type EnumValue<E extends { values: readonly string[] }> = E[\"values\"][number];\n\nexport const createEnum = <const T extends readonly string[]>(values: T): Enum<T> => {\n  if (values.length === 0) {\n    throw new Error(\"Enum must have at least one value\");\n  }\n\n  const uniqueValues = new Set(values);\n  if (uniqueValues.size !== values.length) {\n    throw new Error(\"Enum values must be unique\");\n  }\n\n  const valueSet = new Set<string>(values);\n\n  const base: EnumBase<T> = {\n    values,\n\n    is: (value: unknown): value is T[number] => typeof value === \"string\" && valueSet.has(value),\n\n    assert: (value: unknown): T[number] => {\n      if (typeof value === \"string\" && valueSet.has(value)) {\n        return value as T[number];\n      }\n      throw new Error(`Invalid enum value: \"${value}\". Expected one of: ${values.join(\", \")}`);\n    },\n\n    random: (): T[number] => {\n      const index = Math.floor(Math.random() * values.length);\n      return values[index] as T[number];\n    },\n\n    indexOf: (value: T[number]): number => values.indexOf(value),\n\n    at: (index: number): T[number] | undefined => values.at(index) as T[number] | undefined,\n  };\n\n  const members = Object.fromEntries(values.map((v) => [v, v])) as EnumMembers<T>;\n\n  return Object.freeze({ ...base, ...members }) as Enum<T>;\n};\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@envind/ts-enum-utils",
+  "version": "1.0.0",
+  "description": "Type-safe runtime enums with built-in utilities for TypeScript",
+  "author": "Florin Cuzeac",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "prepublishOnly": "pnpm run lint && pnpm run test && pnpm run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "typescript",
+    "enum",
+    "type-safe",
+    "runtime",
+    "validation",
+    "utilities"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/envindavsorg/ts-enum-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/envindavsorg/ts-enum-utils/issues"
+  },
+  "homepage": "https://github.com/envindavsorg/ts-enum-utils#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.25.0"
+}