# StringSchema

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

`StringSchema` validates that an input is a JavaScript `string` and optionally enforces structural constraints: minimum/maximum length, exact length, regex pattern, email format, URL format, UUID format, prefix/suffix/substring checks. It also supports output transforms (trim, toLowerCase, toUpperCase) applied before constraint evaluation. Every builder method returns a new instance, making the API fully immutable.

This schema is the most commonly used primitive in form and API validation. All constraints are evaluated in a single `_parse` call with no heap allocation beyond the output string, making it suitable for high-frequency validation paths.

## Features

- Type check: rejects non-string with `VALIDATION.INVALID_TYPE`
- `min(n)` / `max(n)` / `length(n)` — length constraints
- `regex(re)` — arbitrary pattern matching
- `email()` — basic RFC-style email check (`user@domain.tld`)
- `url()` — requires `http://` or `https://` prefix
- `uuid()` — 36-character UUID v4-style regex
- `startsWith(prefix)` / `endsWith(suffix)` / `includes(substr)` — substring checks
- `trim()` / `toLowerCase()` / `toUpperCase()` — output transforms

## Usage: Basic Example

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

const username = string().min(3).max(20);
const result = username.safeParse("alice");
// { success: true, data: "alice" }
```

## Usage: Advanced Example

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

// Email with domain block refinement
const email = string()
  .email()
  .toLowerCase()
  .trim()
  .refine((v) => !v.endsWith("@spam.com"), "Spam domains not allowed")
  .describe("User contact email");

// UUID validator
const id = string().uuid().describe("Resource identifier");

// URL with path check
const webhookUrl = string()
  .url()
  .startsWith("https://")
  .includes("/webhook");
```

## API Reference

### `string(): StringSchema`

Factory returning an unconstrained `StringSchema`.

### Constraint methods (all return new `StringSchema`)

| Method | Error code | Description |
|--------|-----------|-------------|
| `min(n)` | `STRING.TOO_SHORT` | Length must be ≥ n |
| `max(n)` | `STRING.TOO_LONG` | Length must be ≤ n |
| `length(n)` | `STRING.INVALID_FORMAT` | Length must be exactly n |
| `regex(re)` | `STRING.INVALID_FORMAT` | Must match regex |
| `email()` | `STRING.INVALID_FORMAT` | Must be valid email |
| `url()` | `STRING.INVALID_FORMAT` | Must start with `http://` or `https://` |
| `uuid()` | `STRING.INVALID_FORMAT` | Must be valid UUID |
| `startsWith(p)` | `STRING.INVALID_FORMAT` | Must begin with prefix p |
| `endsWith(s)` | `STRING.INVALID_FORMAT` | Must end with suffix s |
| `includes(sub)` | `STRING.INVALID_FORMAT` | Must contain substring |

### Transform methods (all return new `StringSchema`)

| Method | Effect |
|--------|--------|
| `trim()` | `String.prototype.trim()` before checks |
| `toLowerCase()` | Converts to lowercase before checks |
| `toUpperCase()` | Converts to uppercase before checks |

## Implementation Notes

- Transforms are applied before constraint checks. This means `string().trim().min(3)` validates the trimmed string.
- The email regex (`/^[^\s@]+@[^\s@]+\.[^\s@]+$/`) is intentionally simple — RFC 5321 compliance is not the goal; rejecting obviously malformed inputs is.
- `uuid()` uses a case-insensitive regex matching the standard 8-4-4-4-12 hex format.
- All builder methods create new `StringSchema` instances via spread of `_constraints`, so chaining is safe across branches.