Schemas and adapters

Standard Schema is the default

An enumwaii declaration is already a Standard Schema v1 schema. Pass the declaration itself to a compatible library; no wrapper or adapter is necessary.

const roles = em(["ADMIN", "USER"]);

form.register("role", roles);
router.input(roles);

Enumwaii uses the official StandardSchemaV1 type from @standard-schema/spec, but does not re-export it. Import the type from the official package when authoring a generic Standard Schema integration:

import type { StandardSchemaV1 } from "@standard-schema/spec";

The spec package is a regular enumwaii dependency because its type appears in enumwaii's public declarations. It contributes no validation runtime of its own. Applications that name the type in their own source should also declare the spec package directly instead of relying on a transitive dependency.

@standard-schema/utils is not required by enumwaii. It is useful to authors of generic Standard Schema tooling, but adding it to the runtime package would not improve declaration validation or the consumer API.

Library-specific adapters

Choose the adapter required by the surrounding API. The package-manager choice is shared with every other install command in these docs.

npm install zod

import { z } from "zod";
import { em } from "enumwaii";
import { emToZodSchema } from "enumwaii/zod";

const roles = em(["ADMIN", "USER"]);
const inputSchema = z.object({
  role: emToZodSchema(roles),
});

const input = inputSchema.parse(payload);
// input.role is the branded enumwaii member union

Both library adapters are separate package entry points and both validator packages are optional peers. Applications that use only Standard Schema do not load either integration.

nuqs query parsers

Install nuqs when URL query state should use enumwaii's validation and branded member type:

npm install nuqs

For a shared default, create the parser beside the declaration and export both:

import { em } from "enumwaii";
import { createEnumwaiiQueryParser } from "enumwaii/nuqs";

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

When the default depends on component state or props, create it inside the component:

import { useQueryState } from "nuqs";
import { em } from "enumwaii";
import { createEnumwaiiQueryParser } from "enumwaii/nuqs";

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

export function RoleFilter({ defaultRole }: { defaultRole: Role }) {
  const parser = createEnumwaiiQueryParser(roles, defaultRole);
  const [role, setRole] = useQueryState("role", parser);

  return <button onClick={() => setRole(ROLE.ADMIN)}>{role}</button>;
}

The parser returns null for invalid query strings as required by nuqs, applies the supplied owned member as its default, and serializes members as their raw string value. The enumwaii/nuqs entry point and nuqs peer are optional; applications that do not import it do not load nuqs.