# TupleSchema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`TupleSchema<T>` validates fixed-length arrays where each positional element has its own schema. Unlike `ArraySchema` (homogeneous elements), `TupleSchema` is heterogeneous: position 0 can be a `string`, position 1 a `number`, etc. It strictly enforces both the array type and the exact length.

## Features

- Type check: rejects non-arrays with `VALIDATION.INVALID_TYPE`
- Length check: rejects arrays with wrong length with `VALIDATION.INVALID_TYPE`
- Per-position schema validation with positional error paths

## Usage: Basic Example

```typescript
import { tuple, string, number } from "@suaveplan/validation";

const coord = tuple([number(), number()]);
coord.parse([48.8566, 2.3522]); // [48.8566, 2.3522]
coord.parse([48.8566]); // throws (wrong length)
```

## Usage: Advanced Example

```typescript
import { tuple, string, number, boolean } from "@suaveplan/validation";

// CSV row parser: [id, name, score, active]
const row = tuple([string().uuid(), string().min(1), number(), boolean()]);

const result = row.safeParse(["550e8400-e29b-41d4-a716-446655440000", "Alice", 99, true]);
```

## API Reference

### `tuple<T extends AnySchema[]>(schemas: T): TupleSchema<T>`

Factory accepting an ordered array of schemas.

### `_parse(input, ctx): TupleOutputs<T> | INVALID`

Validates input is an array of the exact expected length, then parses each element against its positional schema.

## Implementation Notes

- Length mismatch is reported as `VALIDATION.INVALID_TYPE` (no dedicated `TUPLE` code) with a descriptive message including both expected and actual lengths.
- Error paths include the element index: `[...parentPath, i]`.
- Empty tuples `tuple([])` are valid and accept only `[]`.

### Parse Behaviour

`z.tuple([a, b, c])` validates fixed-length arrays where each position has a distinct schema. Extra trailing items are rejected unless you add a rest element with `.rest(schema)`. Inferred output is a typed tuple (`[A, B, C]`) rather than an array, so downstream destructuring stays fully typed.