StringSchema

(no submodules)

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

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

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

Usage: Advanced Example

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.

3.5 KiB Raw Blame History