Getting started

Enumwaii is for string vocabularies that cross application boundaries: roles, states, event types, permissions, provider values, and other sets where a raw string is easy to mistype or source from the wrong place.

Install

Use the package manager that owns the application:

npm install enumwaii

The package ships ESM and CommonJS builds with declarations and source maps. Node.js 18 or newer is supported, and the ESM entry point is also tested under Bun, Deno, and Cloudflare Workers without Node compatibility flags. In a Cloudflare Workers project, use whichever package manager already owns the project and import enumwaii normally.

The only runtime dependency is the type-focused official Standard Schema specification package. Zod, Valibot, and ESLint are opt-in.

Declare and extract

import { em } from "enumwaii";

export const roles = em(["ADMIN", "USER", "GUEST"]);
export const ROLE = roles.enum;
export type Role = (typeof roles)["~type"];

Hover an identifier in any TypeScript example in these guides to inspect the same inferred type and API documentation that an editor would show.

Use the extracted member object in application code:

function canDelete(role: Role): boolean {
  return role === ROLE.ADMIN;
}

canDelete(ROLE.ADMIN); // valid
canDelete("ADMIN"); // TypeScript error
Argument of type '"ADMIN"' is not assignable to parameter of type '("ADMIN" & EnumwaiiBrand<"enumwaii:ADMIN" | "enumwaii:USER" | "enumwaii:GUEST", "ADMIN">) | ("USER" & EnumwaiiBrand<"enumwaii:ADMIN" | "enumwaii:USER" | "enumwaii:GUEST", "USER">) | ("GUEST" & EnumwaiiBrand<...>)'.

Enumwaii deliberately requires this brand. At runtime ROLE.ADMIN is still the ordinary string "ADMIN"; at compile time it proves that the value came from a compatible declaration.

Parse external input

JSON, form fields, route parameters, database rows, and agent output are untrusted even when TypeScript gives their container a convenient shape.

const role = roles.parse(payload.role);

const result = roles.safeParse(searchParams.get("role"));
if (result.success) {
  renderFor(result.value);
} else {
  reportInvalidRole(result.error);
}

Use default for missing values and fallback for any invalid value:

roles.parse(input, { default: ROLE.GUEST });
roles.parse(input, { fallback: ROLE.USER });
roles.parse(input, {
  default: ROLE.GUEST,
  fallback: ROLE.USER,
});

For a nil input, default wins. For any other non-member input, fallback applies. With neither option, parse throws EnumwaiiParseError and safeParse returns its failure branch.

Pass it as a schema

Every declaration implements Standard Schema v1, so compatible libraries can accept it directly:

registerField({ schema: roles });

const result = await roles["~standard"].validate(input);

If an integration requires a library-specific schema type, use the optional Zod or Valibot adapter.

Continue

• API essentials is the practical surface map.
• Member surfaces explains the narrow uses of .rawEnum, .rawValues, and .cases.
• Runtime boundaries covers validation and serialization.
• AI agents provides the packaged skill, machine-readable docs, and ready-to-run setup and migration-analysis prompts.
• Runnable examples show the library in full applications.