ts-safe-enum 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maryan Mats
+
+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,260 @@
+# ts-safe-enum
+
+A tiny, type-safe alternative to TypeScript enums. Built on plain objects with full inference — no `as const` needed, no runtime surprises.
+
+[![npm](https://img.shields.io/npm/v/ts-safe-enum)](https://www.npmjs.com/package/ts-safe-enum)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/ts-safe-enum)](https://bundlephobia.com/package/ts-safe-enum)
+[![license](https://img.shields.io/npm/l/ts-safe-enum)](./LICENSE)
+
+## Why?
+
+TypeScript enums look simple but hide real problems:
+
+- **Numeric enums** generate reverse mappings and accept any number at runtime
+- **String enums** behave like nominal types — they reject identical string values from APIs and localStorage
+- **`const enum`** gets inlined away and breaks with declaration files, barrel exports, and modern toolchains
+- **All enums** compile to IIFEs that bundlers can't tree-shake
+
+The community solution is `as const` objects with union types. But working with them requires boilerplate — `Object.values()` loses type info, there's no type guard, no validation, no reverse lookup.
+
+`ts-safe-enum` gives you a single function that turns a plain object into a fully typed enum with utilities — **zero dependencies, under 1KB**.
+
+> **Read the full philosophy:** [Why I Stopped Using Enums in TypeScript](https://maryanmats.dev/blog/why-i-stopped-using-enums-in-typescript)
+
+## Install
+
+```bash
+npm install ts-safe-enum
+# or
+pnpm add ts-safe-enum
+# or
+yarn add ts-safe-enum
+# or
+bun add ts-safe-enum
+```
+
+## Quick Start
+
+```typescript
+import { defineEnum, type InferValue } from 'ts-safe-enum';
+
+const Status = defineEnum({
+  Active: 'active',
+  Inactive: 'inactive',
+  Pending: 'pending',
+});
+
+// Extract the union type — no `as const` needed
+type Status = InferValue<typeof Status>;
+// 'active' | 'inactive' | 'pending'
+```
+
+## API
+
+### `defineEnum(definition)` — Create a type-safe enum
+
+Accepts a plain object. Literal types are inferred automatically.
+
+```typescript
+const Direction = defineEnum({
+  Up: 'up',
+  Down: 'down',
+  Left: 'left',
+  Right: 'right',
+});
+```
+
+---
+
+### `.values()` — Get all values as a typed array
+
+```typescript
+Status.values();
+// readonly ['active', 'inactive', 'pending']
+```
+
+### `.keys()` — Get all keys as a typed array
+
+```typescript
+Status.keys();
+// readonly ['Active', 'Inactive', 'Pending']
+```
+
+### `.entries()` — Get all key-value pairs
+
+```typescript
+Status.entries();
+// readonly [['Active', 'active'], ['Inactive', 'inactive'], ['Pending', 'pending']]
+```
+
+---
+
+### `.is(value)` — Type guard for unknown values
+
+Narrows `unknown` to the enum's value union:
+
+```typescript
+const input: unknown = getUserInput();
+
+if (Status.is(input)) {
+  // input is narrowed to 'active' | 'inactive' | 'pending'
+  console.log(`Valid status: ${input}`);
+}
+```
+
+### `.parse(value)` — Validate with a Result
+
+Returns `{ ok: true, value }` or `{ ok: false, error }`:
+
+```typescript
+const result = Status.parse(apiResponse.status);
+
+if (result.ok) {
+  console.log(result.value); // typed as 'active' | 'inactive' | 'pending'
+} else {
+  console.error(result.error);
+  // 'Invalid enum value: "unknown". Expected one of: active, inactive, pending'
+}
+```
+
+> If [`ts-safe-result`](https://www.npmjs.com/package/ts-safe-result) is installed, `.parse()` returns a full `Result` with `.map()`, `.match()`, and other utilities.
+
+### `.keyOf(value)` — Reverse lookup
+
+Get the key name for a given value:
+
+```typescript
+Status.keyOf('active');    // 'Active'
+Status.keyOf('inactive');  // 'Inactive'
+```
+
+---
+
+### Type Helpers
+
+#### `InferValue<T>` — Extract the value union type
+
+```typescript
+type Status = InferValue<typeof Status>;
+// 'active' | 'inactive' | 'pending'
+
+function setStatus(status: Status) { /* ... */ }
+setStatus('active');  // ✅
+setStatus('unknown'); // ❌ type error
+```
+
+#### `InferKey<T>` — Extract the key union type
+
+```typescript
+type StatusKey = InferKey<typeof Status>;
+// 'Active' | 'Inactive' | 'Pending'
+```
+
+---
+
+## Real-World Patterns
+
+### Validating API responses
+
+```typescript
+const Role = defineEnum({
+  Admin: 'admin',
+  Editor: 'editor',
+  Viewer: 'viewer',
+});
+
+type Role = InferValue<typeof Role>;
+
+function handleUser(apiData: { role: string }) {
+  const result = Role.parse(apiData.role);
+
+  if (!result.ok) {
+    throw new Error(`Unknown role from API: ${apiData.role}`);
+  }
+
+  const role = result.value; // typed as 'admin' | 'editor' | 'viewer'
+}
+```
+
+### Exhaustive switch statements
+
+```typescript
+const Theme = defineEnum({
+  Light: 'light',
+  Dark: 'dark',
+  System: 'system',
+});
+
+type Theme = InferValue<typeof Theme>;
+
+function getBackground(theme: Theme): string {
+  switch (theme) {
+    case Theme.definition.Light:  return '#ffffff';
+    case Theme.definition.Dark:   return '#1a1a1a';
+    case Theme.definition.System: return getSystemBackground();
+  }
+}
+```
+
+### Iterating over values
+
+```typescript
+const Priority = defineEnum({
+  Low: 1,
+  Medium: 2,
+  High: 3,
+  Critical: 4,
+});
+
+// Render a dropdown
+Priority.entries().map(([label, value]) => (
+  <option key={value} value={value}>{label}</option>
+));
+```
+
+### With `ts-safe-result`
+
+When both packages are installed, `.parse()` returns a full `Result`:
+
+```typescript
+import { defineEnum } from 'ts-safe-enum';
+
+const Color = defineEnum({
+  Red: 'red',
+  Green: 'green',
+  Blue: 'blue',
+});
+
+Color.parse(userInput).match({
+  ok:  color => applyColor(color),
+  err: message => showError(message),
+});
+```
+
+## Comparison
+
+| Feature | ts-safe-enum | TS enum | `as const` + manual | ts-enum-util |
+|---|---|---|---|---|
+| Tree-shakable | Yes | No (IIFEs) | Yes | Partial |
+| No reverse mapping | Yes | No (numeric) | Yes | No |
+| Type guard (`.is()`) | Yes | No | Manual | Yes |
+| Validation (`.parse()`) | Yes | No | Manual | No |
+| Reverse lookup | Yes | Numeric only | Manual | Yes |
+| `as const` required | No | N/A | Yes | N/A |
+| Works with real enums | No | Yes | No | Yes |
+| Bundle size | < 1KB | ~0 (inlined) | 0 | ~3KB |
+
+## Part of the ts-safe family
+
+- [`ts-safe-result`](https://www.npmjs.com/package/ts-safe-result) — Type-safe `Result<Value, Error>` for TypeScript
+- [`ts-safe-enum`](https://www.npmjs.com/package/ts-safe-enum) — Type-safe enum alternative (you are here)
+
+## Philosophy
+
+1. **Plain objects over magic.** An enum should be a plain object that TypeScript understands completely — no code generation, no IIFEs, no reverse mappings.
+2. **Inference over annotation.** You shouldn't need `as const`, type aliases, or helper types just to define a set of constants.
+3. **Validate at boundaries.** APIs send strings, localStorage stores strings, URLs contain strings. `.is()` and `.parse()` handle the real world.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';function l(n){let s=Object.values(n),u=Object.keys(n),a=Object.entries(n),t=new Set(Object.values(n)),o=new Map;for(let[e,r]of Object.entries(n))o.set(r,e);return {definition:n,values(){return s},keys(){return u},entries(){return a},is(e){return t.has(e)},parse(e){if(t.has(e))return {ok:true,value:e};let r=s.map(String).join(", ");return {ok:false,error:`Invalid enum value: "${String(e)}". Expected one of: ${r}`}},keyOf(e){return o.get(e)}}}exports.defineEnum=l;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["defineEnum","definition","allValues","allKeys","allEntries","valueSet","reverseLookup","key","value","validValues"],"mappings":"aAiFO,SAASA,CAAAA,CACdC,CAAAA,CACiB,CACjB,IAAMC,CAAAA,CAAY,MAAA,CAAO,MAAA,CAAOD,CAAU,CAAA,CACpCE,CAAAA,CAAU,MAAA,CAAO,IAAA,CAAKF,CAAU,EAChCG,CAAAA,CAAa,MAAA,CAAO,OAAA,CAAQH,CAAU,CAAA,CAEtCI,CAAAA,CAAW,IAAI,GAAA,CAAqB,MAAA,CAAO,MAAA,CAAOJ,CAAU,CAAC,CAAA,CAC7DK,CAAAA,CAAgB,IAAI,GAAA,CAE1B,IAAA,GAAW,CAACC,CAAAA,CAAKC,CAAK,CAAA,GAAK,MAAA,CAAO,OAAA,CAAQP,CAAU,CAAA,CAClDK,CAAAA,CAAc,GAAA,CAAIE,CAAAA,CAAOD,CAAG,CAAA,CAG9B,OAAO,CACL,UAAA,CAAAN,CAAAA,CAEA,MAAA,EAAS,CACP,OAAOC,CACT,CAAA,CAEA,IAAA,EAAO,CACL,OAAOC,CACT,CAAA,CAEA,OAAA,EAAU,CACR,OAAOC,CACT,CAAA,CAEA,EAAA,CAAGI,CAAAA,CAAqC,CACtC,OAAOH,CAAAA,CAAS,GAAA,CAAIG,CAAwB,CAC9C,CAAA,CAEA,KAAA,CAAMA,CAAAA,CAAyC,CAC7C,GAAIH,CAAAA,CAAS,GAAA,CAAIG,CAAwB,CAAA,CACvC,OAAO,CAAE,EAAA,CAAI,IAAA,CAAM,KAAA,CAAOA,CAAoB,CAAA,CAGhD,IAAMC,CAAAA,CAAcP,CAAAA,CAAU,IAAI,MAAM,CAAA,CAAE,IAAA,CAAK,IAAI,CAAA,CACnD,OAAO,CACL,EAAA,CAAI,KAAA,CACJ,KAAA,CAAO,CAAA,qBAAA,EAAwB,MAAA,CAAOM,CAAK,CAAC,CAAA,oBAAA,EAAuBC,CAAW,CAAA,CAChF,CACF,CAAA,CAEA,KAAA,CAAMD,CAAAA,CAAmB,CACvB,OAAOF,CAAAA,CAAc,GAAA,CAAIE,CAAwB,CACnD,CACF,CACF","file":"index.cjs","sourcesContent":["/**\n * The type of values in an enum definition.\n * Extracted as a union of all values.\n */\nexport type InferValue<T extends EnumInstance<Record<string, string | number>>> =\n  ReturnType<T[\"values\"]>[number];\n\n/**\n * The type of keys in an enum definition.\n * Extracted as a union of all keys.\n */\nexport type InferKey<T extends EnumInstance<Record<string, string | number>>> =\n  ReturnType<T[\"keys\"]>[number];\n\n/** The result of `.parse()` — compatible with `ts-safe-result`'s Result shape. */\nexport type ParseResult<Value> =\n  | { readonly ok: true; readonly value: Value }\n  | { readonly ok: false; readonly error: string };\n\nexport interface EnumInstance<T extends Record<string, string | number>> {\n  /** The original definition object. */\n  readonly definition: T;\n\n  /** Get all values as a readonly array. */\n  values(): readonly T[keyof T][];\n\n  /** Get all keys as a readonly array. */\n  keys(): readonly (keyof T)[];\n\n  /** Get all entries as readonly [key, value] pairs. */\n  entries(): readonly (readonly [keyof T, T[keyof T]])[];\n\n  /**\n   * Type guard — check if an unknown value is a valid enum value.\n   *\n   * @example\n   * if (Status.is(input)) {\n   *   // input is narrowed to 'active' | 'inactive' | 'pending'\n   * }\n   */\n  is(value: unknown): value is T[keyof T];\n\n  /**\n   * Parse an unknown value into a typed enum value.\n   * Returns `{ ok: true, value }` or `{ ok: false, error }`.\n   *\n   * The shape is compatible with `ts-safe-result` — you can wrap it\n   * with `ok()`/`err()` for full chaining support.\n   */\n  parse(value: unknown): ParseResult<T[keyof T]>;\n\n  /**\n   * Get the key corresponding to a given value.\n   * Returns undefined if the value is not in the enum.\n   *\n   * @example\n   * Status.keyOf('active') // 'Active'\n   */\n  keyOf(value: T[keyof T]): keyof T | undefined;\n}\n\n/**\n * Define a type-safe enum from a plain object.\n * No `as const` needed — literal types are inferred automatically.\n *\n * @example\n * const Status = defineEnum({\n *   Active: 'active',\n *   Inactive: 'inactive',\n *   Pending: 'pending',\n * });\n *\n * type Status = InferValue<typeof Status>;\n * // 'active' | 'inactive' | 'pending'\n *\n * Status.values()       // ['active', 'inactive', 'pending']\n * Status.keys()         // ['Active', 'Inactive', 'Pending']\n * Status.is('active')   // true (type guard)\n * Status.parse('xxx')   // { ok: false, error: '...' }\n * Status.keyOf('active') // 'Active'\n */\nexport function defineEnum<const T extends Record<string, string | number>>(\n  definition: T,\n): EnumInstance<T> {\n  const allValues = Object.values(definition) as unknown as T[keyof T][];\n  const allKeys = Object.keys(definition) as unknown as (keyof T)[];\n  const allEntries = Object.entries(definition) as unknown as (readonly [keyof T, T[keyof T]])[];\n\n  const valueSet = new Set<string | number>(Object.values(definition));\n  const reverseLookup = new Map<string | number, string>();\n\n  for (const [key, value] of Object.entries(definition)) {\n    reverseLookup.set(value, key);\n  }\n\n  return {\n    definition,\n\n    values() {\n      return allValues;\n    },\n\n    keys() {\n      return allKeys;\n    },\n\n    entries() {\n      return allEntries;\n    },\n\n    is(value: unknown): value is T[keyof T] {\n      return valueSet.has(value as string | number);\n    },\n\n    parse(value: unknown): ParseResult<T[keyof T]> {\n      if (valueSet.has(value as string | number)) {\n        return { ok: true, value: value as T[keyof T] };\n      }\n\n      const validValues = allValues.map(String).join(\", \");\n      return {\n        ok: false,\n        error: `Invalid enum value: \"${String(value)}\". Expected one of: ${validValues}`,\n      };\n    },\n\n    keyOf(value: T[keyof T]) {\n      return reverseLookup.get(value as string | number) as keyof T | undefined;\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+/**
+ * The type of values in an enum definition.
+ * Extracted as a union of all values.
+ */
+type InferValue<T extends EnumInstance<Record<string, string | number>>> = ReturnType<T["values"]>[number];
+/**
+ * The type of keys in an enum definition.
+ * Extracted as a union of all keys.
+ */
+type InferKey<T extends EnumInstance<Record<string, string | number>>> = ReturnType<T["keys"]>[number];
+/** The result of `.parse()` — compatible with `ts-safe-result`'s Result shape. */
+type ParseResult<Value> = {
+    readonly ok: true;
+    readonly value: Value;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+interface EnumInstance<T extends Record<string, string | number>> {
+    /** The original definition object. */
+    readonly definition: T;
+    /** Get all values as a readonly array. */
+    values(): readonly T[keyof T][];
+    /** Get all keys as a readonly array. */
+    keys(): readonly (keyof T)[];
+    /** Get all entries as readonly [key, value] pairs. */
+    entries(): readonly (readonly [keyof T, T[keyof T]])[];
+    /**
+     * Type guard — check if an unknown value is a valid enum value.
+     *
+     * @example
+     * if (Status.is(input)) {
+     *   // input is narrowed to 'active' | 'inactive' | 'pending'
+     * }
+     */
+    is(value: unknown): value is T[keyof T];
+    /**
+     * Parse an unknown value into a typed enum value.
+     * Returns `{ ok: true, value }` or `{ ok: false, error }`.
+     *
+     * The shape is compatible with `ts-safe-result` — you can wrap it
+     * with `ok()`/`err()` for full chaining support.
+     */
+    parse(value: unknown): ParseResult<T[keyof T]>;
+    /**
+     * Get the key corresponding to a given value.
+     * Returns undefined if the value is not in the enum.
+     *
+     * @example
+     * Status.keyOf('active') // 'Active'
+     */
+    keyOf(value: T[keyof T]): keyof T | undefined;
+}
+/**
+ * Define a type-safe enum from a plain object.
+ * No `as const` needed — literal types are inferred automatically.
+ *
+ * @example
+ * const Status = defineEnum({
+ *   Active: 'active',
+ *   Inactive: 'inactive',
+ *   Pending: 'pending',
+ * });
+ *
+ * type Status = InferValue<typeof Status>;
+ * // 'active' | 'inactive' | 'pending'
+ *
+ * Status.values()       // ['active', 'inactive', 'pending']
+ * Status.keys()         // ['Active', 'Inactive', 'Pending']
+ * Status.is('active')   // true (type guard)
+ * Status.parse('xxx')   // { ok: false, error: '...' }
+ * Status.keyOf('active') // 'Active'
+ */
+declare function defineEnum<const T extends Record<string, string | number>>(definition: T): EnumInstance<T>;
+
+export { type EnumInstance, type InferKey, type InferValue, type ParseResult, defineEnum };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The type of values in an enum definition.
+ * Extracted as a union of all values.
+ */
+type InferValue<T extends EnumInstance<Record<string, string | number>>> = ReturnType<T["values"]>[number];
+/**
+ * The type of keys in an enum definition.
+ * Extracted as a union of all keys.
+ */
+type InferKey<T extends EnumInstance<Record<string, string | number>>> = ReturnType<T["keys"]>[number];
+/** The result of `.parse()` — compatible with `ts-safe-result`'s Result shape. */
+type ParseResult<Value> = {
+    readonly ok: true;
+    readonly value: Value;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+interface EnumInstance<T extends Record<string, string | number>> {
+    /** The original definition object. */
+    readonly definition: T;
+    /** Get all values as a readonly array. */
+    values(): readonly T[keyof T][];
+    /** Get all keys as a readonly array. */
+    keys(): readonly (keyof T)[];
+    /** Get all entries as readonly [key, value] pairs. */
+    entries(): readonly (readonly [keyof T, T[keyof T]])[];
+    /**
+     * Type guard — check if an unknown value is a valid enum value.
+     *
+     * @example
+     * if (Status.is(input)) {
+     *   // input is narrowed to 'active' | 'inactive' | 'pending'
+     * }
+     */
+    is(value: unknown): value is T[keyof T];
+    /**
+     * Parse an unknown value into a typed enum value.
+     * Returns `{ ok: true, value }` or `{ ok: false, error }`.
+     *
+     * The shape is compatible with `ts-safe-result` — you can wrap it
+     * with `ok()`/`err()` for full chaining support.
+     */
+    parse(value: unknown): ParseResult<T[keyof T]>;
+    /**
+     * Get the key corresponding to a given value.
+     * Returns undefined if the value is not in the enum.
+     *
+     * @example
+     * Status.keyOf('active') // 'Active'
+     */
+    keyOf(value: T[keyof T]): keyof T | undefined;
+}
+/**
+ * Define a type-safe enum from a plain object.
+ * No `as const` needed — literal types are inferred automatically.
+ *
+ * @example
+ * const Status = defineEnum({
+ *   Active: 'active',
+ *   Inactive: 'inactive',
+ *   Pending: 'pending',
+ * });
+ *
+ * type Status = InferValue<typeof Status>;
+ * // 'active' | 'inactive' | 'pending'
+ *
+ * Status.values()       // ['active', 'inactive', 'pending']
+ * Status.keys()         // ['Active', 'Inactive', 'Pending']
+ * Status.is('active')   // true (type guard)
+ * Status.parse('xxx')   // { ok: false, error: '...' }
+ * Status.keyOf('active') // 'Active'
+ */
+declare function defineEnum<const T extends Record<string, string | number>>(definition: T): EnumInstance<T>;
+
+export { type EnumInstance, type InferKey, type InferValue, type ParseResult, defineEnum };

package/dist/index.js

@@ -0,0 +1,2 @@
+function l(n){let s=Object.values(n),u=Object.keys(n),a=Object.entries(n),t=new Set(Object.values(n)),o=new Map;for(let[e,r]of Object.entries(n))o.set(r,e);return {definition:n,values(){return s},keys(){return u},entries(){return a},is(e){return t.has(e)},parse(e){if(t.has(e))return {ok:true,value:e};let r=s.map(String).join(", ");return {ok:false,error:`Invalid enum value: "${String(e)}". Expected one of: ${r}`}},keyOf(e){return o.get(e)}}}export{l as defineEnum};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["defineEnum","definition","allValues","allKeys","allEntries","valueSet","reverseLookup","key","value","validValues"],"mappings":"AAiFO,SAASA,CAAAA,CACdC,CAAAA,CACiB,CACjB,IAAMC,CAAAA,CAAY,MAAA,CAAO,MAAA,CAAOD,CAAU,CAAA,CACpCE,CAAAA,CAAU,MAAA,CAAO,IAAA,CAAKF,CAAU,EAChCG,CAAAA,CAAa,MAAA,CAAO,OAAA,CAAQH,CAAU,CAAA,CAEtCI,CAAAA,CAAW,IAAI,GAAA,CAAqB,MAAA,CAAO,MAAA,CAAOJ,CAAU,CAAC,CAAA,CAC7DK,CAAAA,CAAgB,IAAI,GAAA,CAE1B,IAAA,GAAW,CAACC,CAAAA,CAAKC,CAAK,CAAA,GAAK,MAAA,CAAO,OAAA,CAAQP,CAAU,CAAA,CAClDK,CAAAA,CAAc,GAAA,CAAIE,CAAAA,CAAOD,CAAG,CAAA,CAG9B,OAAO,CACL,UAAA,CAAAN,CAAAA,CAEA,MAAA,EAAS,CACP,OAAOC,CACT,CAAA,CAEA,IAAA,EAAO,CACL,OAAOC,CACT,CAAA,CAEA,OAAA,EAAU,CACR,OAAOC,CACT,CAAA,CAEA,EAAA,CAAGI,CAAAA,CAAqC,CACtC,OAAOH,CAAAA,CAAS,GAAA,CAAIG,CAAwB,CAC9C,CAAA,CAEA,KAAA,CAAMA,CAAAA,CAAyC,CAC7C,GAAIH,CAAAA,CAAS,GAAA,CAAIG,CAAwB,CAAA,CACvC,OAAO,CAAE,EAAA,CAAI,IAAA,CAAM,KAAA,CAAOA,CAAoB,CAAA,CAGhD,IAAMC,CAAAA,CAAcP,CAAAA,CAAU,IAAI,MAAM,CAAA,CAAE,IAAA,CAAK,IAAI,CAAA,CACnD,OAAO,CACL,EAAA,CAAI,KAAA,CACJ,KAAA,CAAO,CAAA,qBAAA,EAAwB,MAAA,CAAOM,CAAK,CAAC,CAAA,oBAAA,EAAuBC,CAAW,CAAA,CAChF,CACF,CAAA,CAEA,KAAA,CAAMD,CAAAA,CAAmB,CACvB,OAAOF,CAAAA,CAAc,GAAA,CAAIE,CAAwB,CACnD,CACF,CACF","file":"index.js","sourcesContent":["/**\n * The type of values in an enum definition.\n * Extracted as a union of all values.\n */\nexport type InferValue<T extends EnumInstance<Record<string, string | number>>> =\n  ReturnType<T[\"values\"]>[number];\n\n/**\n * The type of keys in an enum definition.\n * Extracted as a union of all keys.\n */\nexport type InferKey<T extends EnumInstance<Record<string, string | number>>> =\n  ReturnType<T[\"keys\"]>[number];\n\n/** The result of `.parse()` — compatible with `ts-safe-result`'s Result shape. */\nexport type ParseResult<Value> =\n  | { readonly ok: true; readonly value: Value }\n  | { readonly ok: false; readonly error: string };\n\nexport interface EnumInstance<T extends Record<string, string | number>> {\n  /** The original definition object. */\n  readonly definition: T;\n\n  /** Get all values as a readonly array. */\n  values(): readonly T[keyof T][];\n\n  /** Get all keys as a readonly array. */\n  keys(): readonly (keyof T)[];\n\n  /** Get all entries as readonly [key, value] pairs. */\n  entries(): readonly (readonly [keyof T, T[keyof T]])[];\n\n  /**\n   * Type guard — check if an unknown value is a valid enum value.\n   *\n   * @example\n   * if (Status.is(input)) {\n   *   // input is narrowed to 'active' | 'inactive' | 'pending'\n   * }\n   */\n  is(value: unknown): value is T[keyof T];\n\n  /**\n   * Parse an unknown value into a typed enum value.\n   * Returns `{ ok: true, value }` or `{ ok: false, error }`.\n   *\n   * The shape is compatible with `ts-safe-result` — you can wrap it\n   * with `ok()`/`err()` for full chaining support.\n   */\n  parse(value: unknown): ParseResult<T[keyof T]>;\n\n  /**\n   * Get the key corresponding to a given value.\n   * Returns undefined if the value is not in the enum.\n   *\n   * @example\n   * Status.keyOf('active') // 'Active'\n   */\n  keyOf(value: T[keyof T]): keyof T | undefined;\n}\n\n/**\n * Define a type-safe enum from a plain object.\n * No `as const` needed — literal types are inferred automatically.\n *\n * @example\n * const Status = defineEnum({\n *   Active: 'active',\n *   Inactive: 'inactive',\n *   Pending: 'pending',\n * });\n *\n * type Status = InferValue<typeof Status>;\n * // 'active' | 'inactive' | 'pending'\n *\n * Status.values()       // ['active', 'inactive', 'pending']\n * Status.keys()         // ['Active', 'Inactive', 'Pending']\n * Status.is('active')   // true (type guard)\n * Status.parse('xxx')   // { ok: false, error: '...' }\n * Status.keyOf('active') // 'Active'\n */\nexport function defineEnum<const T extends Record<string, string | number>>(\n  definition: T,\n): EnumInstance<T> {\n  const allValues = Object.values(definition) as unknown as T[keyof T][];\n  const allKeys = Object.keys(definition) as unknown as (keyof T)[];\n  const allEntries = Object.entries(definition) as unknown as (readonly [keyof T, T[keyof T]])[];\n\n  const valueSet = new Set<string | number>(Object.values(definition));\n  const reverseLookup = new Map<string | number, string>();\n\n  for (const [key, value] of Object.entries(definition)) {\n    reverseLookup.set(value, key);\n  }\n\n  return {\n    definition,\n\n    values() {\n      return allValues;\n    },\n\n    keys() {\n      return allKeys;\n    },\n\n    entries() {\n      return allEntries;\n    },\n\n    is(value: unknown): value is T[keyof T] {\n      return valueSet.has(value as string | number);\n    },\n\n    parse(value: unknown): ParseResult<T[keyof T]> {\n      if (valueSet.has(value as string | number)) {\n        return { ok: true, value: value as T[keyof T] };\n      }\n\n      const validValues = allValues.map(String).join(\", \");\n      return {\n        ok: false,\n        error: `Invalid enum value: \"${String(value)}\". Expected one of: ${validValues}`,\n      };\n    },\n\n    keyOf(value: T[keyof T]) {\n      return reverseLookup.get(value as string | number) as keyof T | undefined;\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ts-safe-enum",
+  "version": "1.0.0",
+  "description": "A tiny, type-safe alternative to TypeScript enums. Built on 'as const' objects with full inference, no runtime surprises.",
+  "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"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "enum",
+    "typescript",
+    "type-safe",
+    "as-const",
+    "const",
+    "union-type",
+    "discriminated-union",
+    "enum-alternative",
+    "object-enum",
+    "string-enum"
+  ],
+  "author": "Maryan Mats <matsmaryan@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maryanmats/ts-safe-enum.git"
+  },
+  "homepage": "https://github.com/maryanmats/ts-safe-enum#readme",
+  "bugs": {
+    "url": "https://github.com/maryanmats/ts-safe-enum/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  }
+}