first commit

docs/foundation/core/utils/src/validate/validate.md

@@ -0,0 +1,86 @@
+# validate
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `validate` module provides lightweight, format-only type-guard validators for common binary encoding formats. Unlike full parsers that decode and reconstruct data, these guards perform only surface-level structural checks — enough to narrow the TypeScript type and reject obviously malformed inputs before passing data to more expensive operations such as cryptographic decoding, database writes, or network transmission. They are intentionally thin so callers pay no allocation cost beyond the guard itself.
+
+## Features
+
+- **`isHex`**: validates that a value is a non-empty, even-length string consisting exclusively of hexadecimal characters (`[A-Fa-f0-9]`). Returns `true` only when the string encodes at least one complete byte (two hex digits). Acts as a TypeScript type guard narrowing `unknown` to `string`.
+- **Zero dependencies**: no external imports — just a regex and a `typeof` check.
+- **TypeScript narrowing**: each guard is declared as a type-predicate (`i is string`) so TypeScript narrows the type in the `if`-branch automatically.
+
+## Usage: Basic Example
+
+```typescript
+import { isHex } from "@suaveplan/utils/validate";
+
+function decodePayload(raw: unknown): Uint8Array {
+  if (!isHex(raw)) {
+    throw new TypeError(`Expected hex string, got ${typeof raw}`);
+  }
+  // TypeScript now knows raw is string
+  const bytes = new Uint8Array(raw.length / 2);
+  for (let i = 0; i < raw.length; i += 2) {
+    bytes[i / 2] = parseInt(raw.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { isHex } from "@suaveplan/utils/validate";
+
+// Validate incoming webhook signature before crypto ops
+function verifySignature(payload: string, sigHeader: unknown): boolean {
+  if (!isHex(sigHeader)) {
+    console.warn("Invalid signature format — expected hex");
+    return false;
+  }
+
+  // sigHeader is now narrowed to string
+  const sigBytes = Buffer.from(sigHeader, "hex");
+  // ... HMAC verification ...
+  return true;
+}
+
+// Use in Zod custom refinement
+import z from "zod";
+const hexStringSchema = z.string().refine(isHex, {
+  message: "Must be a non-empty even-length hexadecimal string",
+});
+```
+
+## API Reference
+
+### `isHex(i: unknown): i is string`
+
+Validate that a value is a well-formed hexadecimal byte string.
+
+| Parameter | Type      | Description              |
+|-----------|-----------|--------------------------|
+| `i`       | `unknown` | Value to test.           |
+
+**Returns:** `boolean` — `true` if and only if `i` is a `string` with length > 0, even length, and only `[A-Fa-f0-9]` characters.
+
+**Does not throw.**
+
+**Rules:**
+
+- Empty string → `false`.
+- Odd-length string → `false` (not a complete sequence of bytes).
+- Any non-hex character (`g`–`z`, `G`–`Z`, digits > 9, symbols) → `false`.
+- Non-string input → `false`.
+
+## Implementation Notes
+
+The guard uses the regex `/^([A-Fa-f0-9]{2})+$/` which enforces both character validity and even length in a single pass. The `+` quantifier (one or more pairs) additionally rejects empty strings without a separate length check.
+
+The function is declared as a `const` arrow (rather than a `function` declaration) to emphasize that it is a pure predicate with no side effects and no prototype overhead.
+
+The regex is compiled once at module load time because it is a literal constant in the regex source, eliminating per-call compilation cost.