PercentageLiteral - API reference

API reference › @evolu/common › Number › PercentageLiteral

PercentageLiteral:  createTypeWithError(
  "PercentageLiteral",
  percentageLiteralSyntax,
  (cause, value): PercentageLiteralError => ({
    type: "PercentageLiteral",
    value,
    cause,
  }),
  (error) =>
    The value ${safelyStringifyUnknownValue(error.value)} is not a percentage literal. Use a value such as "50%" or "12.5%".,
) ;

Defined in: packages/common/src/Number.ts:106

Percentage literal Type with compile-time and runtime validation.

Supported formats:

Integers: 0%, 50%, 100% (0-100)
One decimal place: 0.1%, 12.5%, 99.9% (0.1-99.9)

The decimal digit is never zero, so 12.0% must be written as "12%", and 100% has no decimal form. For computed values or more precision, use Ratio directly.

See Percentage for a type that also accepts Ratio. Use percentageToRatio to convert.

Invalid values produce a PercentageLiteralError.

Example

import {
  assertFalse,
  assertOk,
  assertType,
  PercentageLiteral,
} from "@evolu/common";

// The TypeScript type accepts valid spellings and rejects the rest.
const literal: PercentageLiteral = "12.5%";
assertType<Extract<PercentageLiteral, "101%" | "12.0%" | "12.55%">, never>();

// The runtime Type validates the same grammar.
assertOk(PercentageLiteral.fromUnknown(literal), "12.5%");
assertFalse(PercentageLiteral.is("101%"));