percentage

Validate percentage values. The Percentage primitive ensures numeric values represent valid percentages with optional range constraints.

Examples

Creating percentages

// Direct validation
const pct = a.percentage(75.5)

// Parse with options
const pct = a.percentage.parse(input, { min: 0, max: 100 })

// Convert from decimal (0.755 → 75.5)
const pct = a.percentage.fromDecimal(0.755)

// Convert to decimal (75.5 → 0.755)
const decimal = a.percentage.toDecimal(75.5)

// Check validity without throwing
if (a.percentage.isValid(50)) {
  console.log('Valid percentage')
}

Parsing external data

// Parse unknown input (throws on error)
const pct = a.percentage.parse(userInput)

// Safe parsing (returns result object)
const result = a.percentage.safeParse(userInput)
if (result.success) {
  console.log(`Percentage: ${result.data}%`)
} else {
  console.error(result.error.message)
}

// Parse with range constraints
const pct = a.percentage.parse(userInput, { min: 0, max: 100 })

Using with forms

const form = a.form({
  name: 'discount',
  fields: {
    discountRate: { type: 'percentage', label: 'Discount Rate', min: 0, max: 50 },
    taxRate: { type: 'percentage', label: 'Tax Rate' }
  }
})

const filled = form.fill({
  fields: {
    discountRate: a.percentage(15),
    taxRate: a.percentage(8.25)
  }
})

API

Direct Call

a.percentage(input: number): number

Pass a number for validation. Returns the validated number, rounded to the configured precision (two decimal places by default), or throws on error.

const pct = a.percentage(75.5)

Static Methods

parse: (input: unknown, options?: PercentageOptions) => number

Parse unknown input (throws on error)

safeParse: (input: unknown, options?: PercentageOptions) => Result<number>

Parse unknown input (returns result object)

isValid: (input: number, options?: PercentageOptions) => boolean

Check if a number is a valid percentage

fromDecimal: (decimal: number) => number

Convert decimal to percentage (0.5 → 50)

toDecimal: (percentage: number) => number

Convert percentage to decimal (50 → 0.5)

PercentageOptions

Option	Type	Description
`min`	`number?`	Minimum allowed value
`max`	`number?`	Maximum allowed value
`precision`	`number?`	Decimal places to round to (default: 2)

Conversion Helpers

// Decimal to percentage
a.percentage.fromDecimal(0.5)    // → 50
a.percentage.fromDecimal(0.125)  // → 12.5
a.percentage.fromDecimal(1.5)    // → 150

// Percentage to decimal
a.percentage.toDecimal(50)       // → 0.5
a.percentage.toDecimal(12.5)     // → 0.125
a.percentage.toDecimal(150)      // → 1.5

Validation

The Percentage primitive validates:

Value must be a finite number (not NaN or Infinity)
Value must satisfy min/max constraints if provided

// Valid
a.percentage(0)
a.percentage(100)
a.percentage(50.5)
a.percentage(-10)   // Negative allowed by default
a.percentage(150)   // Over 100 allowed by default

// With constraints
a.percentage.parse(50, { min: 0, max: 100 })  // Valid
a.percentage.parse(150, { min: 0, max: 100 }) // Throws

// Invalid - throws Error
a.percentage(NaN)

a.percentage(Infinity)

Primitives Overview - All available primitives
Rating - Similar numeric validation
Percentage Field - Percentage field type

percentage
Last updated on