first commit

docs/foundation/data/validation/src/schemas/string/string.md

@@ -0,0 +1,90 @@
+# 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.