feat: add collection-based validators

docs/reference/types/index.md

@@ -8,18 +8,16 @@ Jane’s utility types enforce non-nullability where possible and focus on clear
 
 These are the essential TypeScript types used to define and communicate predictable data states:
 
-* [ValidationResult](./validation-result.md): The mandatory return type for all **Validator** functions. It is a discriminated union that enforces a clear success/failure contract:
-  * **Success**: `{ ok: true; value: T; }`: The validated, typed value.
-  * **Failure**: `{ ok: false; message: string; field: string; }`: Contextual error details.
+- [ValidationResult](./validation-result.md): The mandatory return type for all **Validator** functions. It is a discriminated union that enforces a clear success or failure contract.
 
 ## When to Refer to Type Definitions
 
 You primarily interact with these definitions when:
 
-* Defining the signature for a new guard, normalizer, validator, or parser.
-* Declaring the specific type a function returns after processing data through one of Jane’s layers.
-* Creating custom wrappers or higher-order functions that compose Jane’s utilities.
-* Documenting the input and output expectations of your application's data flow.
+- Defining the signature for a new guard, normalizer, validator, or parser.
+- Declaring the specific type a function returns after processing data through one of Jane’s layers.
+- Creating custom wrappers or higher-order functions that compose Jane’s utilities.
+- Documenting the input and output expectations of your application's data flow.
 
 ## Why Type Definitions Matter
 

docs/reference/types/validation-result.md

@@ -0,0 +1,96 @@
+# ValidationResult
+
+`ValidationResult<T>` is the standard return type for all validators in Jane. It represents the outcome of a validation operation and provides a structured, predictable way to report success or failure without throwing exceptions or mutating input.
+
+Every validator in Jane returns a `ValidationResult<T>` and follows the same contract:
+
+- Success returns the validated value.
+- Failure returns a structured error describing what went wrong.
+- No validator ever throws.
+- No validator ever mutates input.
+
+This type is central to Jane’s clarity‑first philosophy.
+
+## Signature
+
+```ts
+type ValidationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; field: string; message: string };
+```
+
+## Shape
+
+**Success case**:
+
+```ts
+{
+  ok: true;
+  value: T;
+}
+```
+
+- `ok` is always `true`.
+- `value` contains the validated value, guaranteed to satisfy the validator's contract.
+- No additional metadata is included.
+
+**Failure case**:
+
+```ts
+{
+  ok: false;
+  field: string;
+  message: string;
+}
+```
+
+- `ok` is always `false`.
+- `field` identifies the name of the field being validated.
+- `message` provides a human‑readable explanation of the failure.
+- *No exceptions are thrown*; all error information is *returned structurally*.
+
+## Behavior
+
+- Never throws. All validation failures are represented as structured results.
+- Never mutates input. Validators treat all inputs as immutable.
+- Pure and deterministic. The same input always produces the same output.
+- Explicit contracts. Each validator defines exactly what qualifies as a valid value.
+- Composable. Higher‑level validators can combine multiple `ValidationResult` values to build complex validation flows.
+
+## Examples
+
+**Successful validation**:
+
+```ts
+validatePositiveInteger(5, "count")
+// { ok: true, value: 5 }
+
+
+Failed validation
+validatePositiveInteger(-1, "count")
+// {
+//   ok: false,
+//   field: "count",
+//   message: "Value must be a positive integer"
+// }
+```
+
+**Using ValidationResult in application code**:
+
+```ts
+const result = validateNonEmptyString(input, "username");
+
+if (!result.ok) {
+  return respondWithError(result.field, result.message);
+}
+
+const username = result.value;
+// safe to use here
+```
+
+## Notes
+
+- `ValidationResult<T>` is intentionally minimal. It avoids nested structures, error codes, or metadata that could obscure clarity.
+- The `field` property is always required in failure cases to support consistent error reporting in forms, APIs, and logs.
+- Validators *never* coerce values.
+- This type is stable and intended to remain unchanged across major versions of Jane.

docs/reference/validators/collections/index.md

@@ -2,6 +2,10 @@
 
 Collection validators verify that iterable structures, such as arrays, sets, and maps, meet specific size constraints, and ensure that their elements or entries conform to consistent type constraints. They return a structured `ValidationResult<T>`, never throw exceptions, and never mutate the input collection.
 
--
+- [validateMap](./validate-map.md): Ensures a value is a `Map` instance (including wrapper objects and subclasses). Useful for validating key–value collections before applying entry‑level checks.
+- [validateSet](./validate-set.md): Ensures a value is a `Set` instance. Ideal for validating unordered collections of unique values prior to element‑level validation.
+- [validateTypedArray](./validate-typed-array.md): - Ensures a value is one of the built‑in TypedArray variants (including `Int8Array`, `Float32Array`, `BigUint64Array`, and so on). Useful for validating binary buffers and numeric arrays.
+- [validateWeakMap](./validate-weak-map.md): Ensures a value is a `WeakMap` instance. Suitable for validating object‑keyed mappings used in caches, memoization layers, and ephemeral associations.
+- [validateWeakSet](./validate-weak-set.md): Ensures a value is a `WeakSet` instance. Useful for validating object‑keyed membership sets that rely on weak references.
 
 All collection validators are pure, predictable, and designed to perform fast checks on the integrity and size of data structures.

docs/reference/validators/collections/validate-map.md

@@ -0,0 +1,57 @@
+# validateMap
+
+Validates that a value is a **Map** instance. This helper uses the [isMap](../../type-guards/collections/is-map.md) type guard internally. Only native `Map` instances and `Map` wrapper objects created via `Object(...)` pass this check.
+
+It never throws and never mutates input. Use it when you need to validate key–value collections before applying further structural or element‑level validation.
+
+## Signature
+
+```ts
+function validateMap(
+  value: unknown,
+  field: string
+): ValidationResult<Map<unknown, unknown>>
+```
+
+## Parameters
+
+| Name | Data type | Description |
+|---|---|---|
+| value | `unknown` | The value to validate. |
+| field | `string` | The name of the field being validated, used in error reporting. |
+
+## Returns
+
+A `ValidationResult<Map<unknown, unknown>>`:
+
+- `{ ok: true, value: Map }`: If the value is a `Map`.
+- `{ ok: false, field, message }`: Otherwise.
+
+## Behavior
+
+- Uses [isMap](../../type-guards/collections/is-map.md) internally.
+- **Accepts**:
+  - `new Map()`.
+  - `new Map([...])`.
+  - `Object(new Map())`.
+  - Subclasses of `Map`.
+- **Rejects**:
+  - Plain objects
+  - Arrays
+  - Sets, WeakMaps, WeakSets
+  - Primitives
+  - Never throws or mutates input.
+
+## Examples
+
+```ts
+validateMap(new Map([["a", 1]]), "data")
+// { ok: true, value: Map { "a" => 1 } }
+
+validateMap({}, "obj")
+// { ok: false, field: "obj", message: "Value must be a Map" }
+```
+
+## Notes
+
+- This validator checks only that the value is a `Map`. It does not validate key or value types. For that, use higher‑level helpers.

docs/reference/validators/collections/validate-set.md

@@ -0,0 +1,58 @@
+# validateSet
+
+Validates that a value is a **Set** instance. This helper uses the [isSet](../../type-guards/collections/is-set.md) type guard internally. Only native `Set` instances and wrapper objects created via `Object(...)` pass this check.
+
+It never throws and never mutates input. Use it when you need to validate unordered collections of unique values before applying further structural or element-level validation.
+
+## Signature
+
+```ts
+function validateSet(
+  value: unknown,
+  field: string
+): ValidationResult<Set<unknown>>
+```
+
+## Parameters
+
+| Name | Data type | Description |
+|---|---|---|
+| value | `unknown` | The value to validate. |
+| field | `string` | The name of the field being validated, used in error reporting. |
+
+## Returns
+
+One of:
+
+- `{ ok: true, value: Set }`: If value is a `Set`.
+- `{ ok: false, field: string, message: string }`: If value is not a `Set`.
+
+## Behavior
+
+- Uses [isSet](../../type-guards/collections/is-set.md) internally.
+- **Accepts**:
+  - `new Set()`.
+  - `new Set([...])`.
+  - `Object(new Set())`.
+  - Subclasses of `Set`.
+- **Rejects**:
+  - Plain objects.
+  - Arrays.
+  - Maps, WeakSets, WeakMaps.
+  - Primitives.
+  - Never mutates input.
+  - Never throws.
+
+## Examples
+
+```ts
+validateSet(new Set([1, 2, 3]), "numbers")
+// { ok: true, value: Set { 1, 2, 3 } }
+
+validateSet({}, "obj")
+// { ok: false, field: "obj", message: "Value must be a Set" }
+```
+
+## Notes
+
+- This validator checks only that the value is a `Set`. It does not validate element types. For that, use higher-level helpers.

docs/reference/validators/collections/validate-typed-array.md

@@ -0,0 +1,71 @@
+# validateTypedArray
+
+Validates that a value is a **TypedArray** instance. This helper uses the [isTypedArray](../../type-guards/collections/is-typed-array.md) type guard internally. Only native TypedArray instances and wrapper objects created via `Object(...)` pass this check.
+
+It never throws and never mutates input. Use it when you need to validate binary data buffers or numeric arrays before applying further structural or element-level validation.
+
+## Signature
+
+```ts
+function validateTypedArray(
+  value: unknown,
+  field: string
+): ValidationResult<TypedArray>
+```
+
+Where `TypedArray` is the union of all built-in typed array variants:
+
+```ts
+type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array;
+```
+
+| Name | Data type | Description |
+|---|---|---|
+| value | `unknown` | The value to validate. |
+| field | `string` | The name of the field being validated, used in error reporting. |
+
+## Returns
+
+One of:
+
+- `{ ok: true, value: TypedArray }`: If value is a `TypedArray`.
+- `{ ok: false, field: string, message: string }`: If value is not a `TypedArray`.
+
+Behavior
+
+- Uses [isTypedArray](../../type-guards/collections/is-typed-array.md) internally.
+- **Accepts**:
+  - Any built-in `TypedArray` variant.
+  - Wrapper objects created using `Object(new Int8Array(...))`.
+  - Subclasses of `TypedArray`.
+- **Rejects**:
+  - Plain arrays.
+  - Sets, Maps, WeakSets, WeakMaps.
+  - Primitives.
+  - Never mutates input.
+  - Never throws.
+
+## Examples
+
+```ts
+validateTypedArray(new Float32Array([1.1, 2.2]), "floats")
+// { ok: true, value: Float32Array [1.1, 2.2] }
+
+validateTypedArray([1, 2, 3], "arr")
+// { ok: false, field: "arr", message: "Value must be a TypedArray" }
+```
+
+## Notes
+
+- This validator checks only that the value is a `TypedArray`. It does not validate element types or ranges. For that, use higher-level helpers.

docs/reference/validators/collections/validate-weak-map.md

@@ -0,0 +1,44 @@
+# isWeakMap
+
+Checks whether a value is a **WeakMap**.
+
+This helper performs a strict `instanceof` check and never throws or mutates input. It accepts native `WeakMap` instances, `WeakMap` subclasses, and wrapper objects created with `Object(...)`.
+
+## Signature
+
+```ts
+function isWeakMap<K extends object = object, V = unknown>(
+    value: unknown,
+): value is WeakMap<K, V>
+```
+
+## Parameters
+
+| Name | Data type | Description |
+|---|---|---|
+| value | `unknown` | The value to validate. |
+| field | `string` | The name of the field being validated, used in error reporting. |
+
+## Returns
+
+A boolean:
+
+- `true`: If the value is a WeakMap.
+- `false`: Otherwise.
+
+Examples
+
+```ts
+isWeakMap(new WeakMap())          // true
+isWeakMap(Object(new WeakMap()))  // true
+
+isWeakMap(new Map())              // false
+isWeakMap({})                     // false
+isWeakMap(null)                   // false
+```
+
+## Notes
+
+- This helper intentionally accepts `WeakMap` wrapper objects because JavaScript treats them as genuine `WeakMap` instances.
+- It does not treat plain objects or Maps as WeakMaps.
+- Use [validateWeakMap](./validate-weak-map.md) if you need a `Result<T>` instead of a boolean.