# rating

Validate rating values

Canonical URL: https://docs.paradoc.dev/sdk/primitives/rating/

Validate rating values. The Rating primitive ensures numeric values represent valid ratings with optional step alignment and range constraints.

## Examples

### Creating ratings

```ts
// Direct validation (defaults: min=1, max=5, step=1)
const rating = p.rating(4)

// Parse with options for half-star ratings
const rating = p.rating.parse(input, { min: 1, max: 5, step: 0.5 })

// Check validity without throwing
if (p.rating.isValid(4)) {
  console.log('Valid rating')
}
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const rating = p.rating.parse(userInput)

// Safe parsing (returns result object)
const result = p.rating.safeParse(userInput)
if (result.success) {
  console.log(`Rating: ${result.data} stars`)
} else {
  console.error(result.error.message)
}

// Parse with constraints
const rating = p.rating.parse(userInput, {
  min: 1,
  max: 5,
  step: 0.5  // Only allow 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5
})
```

### Using with forms

```ts
const form = p.form({
  name: 'review',
  fields: {
    overallRating: { type: 'rating', label: 'Overall Rating', min: 1, max: 5 },
    serviceRating: { type: 'rating', label: 'Service Rating', min: 1, max: 10 }
  }
})

const filled = form.fill({
  fields: {
    overallRating: p.rating(4),
    serviceRating: p.rating.parse(8, { min: 1, max: 10 })
  }
})
```

## API

### Direct Call

```ts
p.rating(input: number): number
```

Pass a number for validation. Returns the validated number or throws on error.

```ts
const rating = p.rating(4)
```

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown, options?: RatingOptions)` | `number` | Parse unknown input (throws on error) |
| `safeParse(input: unknown, options?: RatingOptions)` | `Result<number>` | Parse unknown input (returns result object) |
| `isValid(input: number, options?: RatingOptions)` | `boolean` | Check if a number is a valid rating |

### RatingOptions

| Option | Type      | Description                                      |
| ------ | --------- | ------------------------------------------------ |
| `min`  | `number?` | Minimum allowed value                            |
| `max`  | `number?` | Maximum allowed value                            |
| `step` | `number?` | Step increment (e.g., 0.5 for half-star ratings) |

## Step Alignment

When a `step` is specified, ratings must align to the step value:

```ts
// Step of 1 (whole stars only)
p.rating.parse(4, { step: 1 })      // Valid: 4
p.rating.parse(4.5, { step: 1 })    // Throws: not aligned

// Step of 0.5 (half stars)
p.rating.parse(4, { step: 0.5 })    // Valid: 4
p.rating.parse(4.5, { step: 0.5 })  // Valid: 4.5
p.rating.parse(4.3, { step: 0.5 })  // Throws: not aligned

// Step of 0.1 (tenths)
p.rating.parse(4.7, { step: 0.1 })  // Valid: 4.7
```

## Common Rating Scales

| Scale      | Range | Step     | Example             |
| ---------- | ----- | -------- | ------------------- |
| 5-star     | 1-5   | 0.5 or 1 | Movie ratings       |
| 10-point   | 1-10  | 1        | Product reviews     |
| Percentage | 0-100 | 1        | Satisfaction scores |
| NPS        | 0-10  | 1        | Net Promoter Score  |

## Validation

The Rating primitive validates:

* Value must be a finite number (not NaN or Infinity)
* Value must satisfy min/max constraints (defaults: min=1, max=5)
* Value must align to step (default: step=1, whole numbers only)

```ts
// Valid with defaults (min=1, max=5, step=1)
p.rating(1)
p.rating(3)
p.rating(5)

// With custom options
p.rating.parse(4.5, { min: 1, max: 5, step: 0.5 }) // Valid: half-stars enabled
p.rating.parse(0, { min: 0, max: 5 })              // Valid: custom min

// Invalid with defaults - throws Error
p.rating(0)

p.rating(4.5)

p.rating(NaN)

p.rating.parse(6, { min: 1, max: 5 })
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Percentage](/sdk/primitives/percentage) - Percentage values
* [Rating Field](/sdk/artifacts/form/field#rating) - Rating field type