@ck0/lib-enum

A tiny TypeScript helper for declaring string-literal-union enums with both an object map and a values list, derived from a single source of truth.

import { createEnum } from "@ck0/lib-enum";

const { object: Mode, list: ModeValues } = createEnum({
    dev: null,
    test: null,
    prod: null,
} as const);

// Mode.dev   === "dev"
// ModeValues === ["dev", "test", "prod"] (as const)

type Mode = (typeof Mode)[keyof typeof Mode];
// type Mode = "dev" | "test" | "prod"

Why this instead of enum?

TypeScript's native enum produces a runtime object with reverse mappings, doesn't pair cleanly with string-literal types, and doesn't give you a values list out of the box. createEnum gives you, from one declaration:

• A typed object (Mode.dev, Mode.test, …) for use in code.
• A readonly tuple of values (ModeValues) for runtime iteration, validation libraries (Zod's z.enum(ModeValues as [...]), etc.), and select dropdowns.
• A derived TypeScript type that's a plain string-literal union — no separate enum type to import.

Three ways to declare

1. Tuple of strings (simplest)

const { object: Architecture, list: ArchitectureValues } = createEnum([
    "amd64",
    "arm64",
] as const);

type Architecture = (typeof Architecture)[keyof typeof Architecture];

2. Object with null values (refactor-friendly)

When you want to rename a key later without touching every callsite:

const { object: Mode, list: ModeValues } = createEnum({
    dev: null,
    test: null,
    prod: null,
} as const);

3. Object with explicit string values

When the key and the runtime value should differ — e.g. the key is the symbolic name, the value is what's stored on disk:

const { object: Mode, list: ModeValues } = createEnum({
    dev: null,           // → "dev"
    test: "testing",     // → "testing"
    prod: undefined,     // → "prod"
} as const);

// Mode.dev  === "dev"
// Mode.test === "testing"
// Mode.prod === "prod"

API

• createEnum(input) — overloaded; dispatches to V1 (tuple) or V2 (record) based on input shape.
• createEnumV1(tuple) — explicit tuple form.
• createEnumV2(record) — explicit record form.

All return { object, list }. The types of both are precisely inferred from the input — no as casts needed at the use site.

Since 0.2.0 every entry point takes a const type parameter (TypeScript ≥ 5.0), so literals are inferred even without as const: createEnum(["amd64", "arm64"]) yields the union "amd64" | "arm64", not string. as const is still accepted and changes nothing. object is typed readonly. A non-literal argument (a variable, a function result) contributes its own type unchanged: one declared as const or with literal property types stays literal, while one already typed wide (string[], { test: string }), or a literal containing such an element, produces a string union.

Breaking type changes in 0.4.0

Runtime behaviour is unchanged. The record form's types now describe what the runtime (Object.keys / Object.values) produces:

• Symbol keys are dropped from the types: for createEnum({ dev: null, [sym]: null }), object and list no longer mention the symbol key, since Object.keys drops it and the runtime enum never had that member. A symbol key whose value is not a string, null or undefined is a type error, like any other key.
• Callable arguments are rejected: createEnum(() => "dev"), and any callable or constructable value, including one with its own string properties such as Object.assign(() => 1, { a: "x" }). A member named call or apply holding a string, null or undefined is still fine.
• A numeric key's value is its string: createEnum({ 200: null }) types object[200] and the list member as "200", not the number 200.
• A union input gives a union of results: for an argument typed { dev: null } | { prod: "production" }, the result is the union of each member's { list, object }. Before, list covered only the keys every member shares, so readonly never[] when they share none.

Breaking type changes in 0.3.0

Runtime behaviour is unchanged. Enum members must now be strings: in 0.2.0 the record form's constraint was Record<string, any>, which every object type satisfies, so these compiled and now are type errors:

• Non-string arrays: createEnum([1, 2]), createEnum(["amd64", 64]), or a number[] variable. They failed the tuple overload, fell through to the record one, and at runtime still took the tuple path.
• Non-string record values: createEnum({ dev: 1 }), { dev: true }, { dev: { wire: "development" } }, or a class instance with a method. Each value must be a string, null or undefined.
• Arrays passed to createEnumV2: createEnumV2(["dev", "prod"]). Use createEnum or createEnumV1 for a list.

Interface-typed variables and class instances whose fields are strings or null are still accepted, and the inferred types of valid inputs are unchanged.

Breaking type changes in 0.2.0

Runtime behaviour is unchanged. Call sites that already used as const keep the same list and value types (only object becomes readonly); call sites that did not now get literal types, which can stop compiling:

• Tuple form: list is a readonly literal tuple instead of string[], so list.push(…) and passing list to a mutable string[] parameter are errors.
• Record form: explicit string values are literals instead of string, so e.g. let m = object.test; m = "other"; is an error.
• All forms: object is readonly, so assigning to its properties is an error.

Install

npm install @ck0/lib-enum
# or
pnpm add @ck0/lib-enum

License

MIT