Validation

Validation: object

Defined in: Core/Validation.ts:42

Type Declaration

apply

apply: {<E2, A>(arg): <B, E1>(validation) => Validation<E2 | E1, B>; <E1, E2, A, E3>(arg, options): <B>(validation) => Validation<E3, B>; }

Applies a function wrapped in a Validation to a value wrapped in a Validation. Accumulates errors from both sides if both fail, using optional combineErrors or default concatenation.

Call Signature

<E2, A>(arg): <B, E1>(validation) => Validation<E2 | E1, B>

Type Parameters

E2

E2 = never

A

A = unknown

Parameters

arg

Validation<E2, A>

Returns

<B, E1>(validation) => Validation<E2 | E1, B>

Call Signature

<E1, E2, A, E3>(arg, options): <B>(validation) => Validation<E3, B>

Type Parameters

E1

E1

E2

E2

A

A

E3

E3

Parameters

arg

Validation<E2, A>

options

combineErrors

(e1, e2) => NonEmptyArr<E3>

Returns

<B>(validation) => Validation<E3, B>

See

Validation.struct to combine record validations.

Example

const add = (a: number) => (b: number) => a + b;
pipe(
  Validation.make.passed(add),
  Validation.apply(Validation.make.passed(5)),
  Validation.apply(Validation.make.passed(3))
); // Passed(8)

pipe(
  Validation.make.passed(add),
  Validation.apply(Validation.make.failed<string>("bad a")),
  Validation.apply(Validation.make.failed<string>("bad b"))
); // Failed(["bad a", "bad b"])

// Custom error combination:
pipe(
  Validation.make.passed(add),
  Validation.apply(Validation.make.failed("err"), {
    combineErrors: (e1, e2) => [...e1, ...e2],
  })
);

from

from: object

from.Maybe

Maybe: <E>(onNone) => <A>(maybe) => Validation<E, A>

Creates a Validation from a Maybe. If the Maybe is None, returns Failed with the error from onNone. Otherwise, returns Passed.

Type Parameters

E

E

Parameters

onNone

() => E

Returns

<A>(maybe) => Validation<E, A>

Example

pipe(Maybe.make.none(), Validation.from.Maybe(() => "is none")); // Failed(["is none"])
pipe(Maybe.make.some(42), Validation.from.Maybe(() => "is none")); // Passed(42)

from.nullable

nullable: <E>(onNull) => <A>(value) => Validation<E, NonNullable<A>>

Creates a Validation from a nullable value. If the value is null or undefined, returns Failed with the error from onNull. Otherwise, returns Passed.

Type Parameters

E

E

Parameters

onNull

() => E

Returns

<A>(value) => Validation<E, NonNullable<A>>

Example

pipe(null, Validation.from.nullable(() => "is null")); // Failed(["is null"])
pipe(42, Validation.from.nullable(() => "is null"));   // Passed(42)

from.Predicate

Predicate: {<A, B, E>(refinement, onFalse): (value) => Validation<E, B>; <A, E>(predicate, onFalse): (value) => Validation<E, A>; }

Creates a Validation from a predicate applied to a value. Returns Passed if the predicate passes, Failed from onFalse otherwise.

Call Signature

<A, B, E>(refinement, onFalse): (value) => Validation<E, B>

Type Parameters

A

A

B

B

E

E

Parameters

refinement

(value) => value is B

onFalse

(value) => E

Returns

(value) => Validation<E, B>

Call Signature

<A, E>(predicate, onFalse): (value) => Validation<E, A>

Type Parameters

A

A

E

E

Parameters

predicate

(value) => boolean

onFalse

(value) => E

Returns

(value) => Validation<E, A>

Example

const validateName = Validation.from.Predicate(
  (s: string) => s.length > 0,
  () => "Name is required"
);

validateName("Alice"); // Passed("Alice")
validateName("");      // Failed(["Name is required"])

from.Result

Result: <E, A>(result) => Validation<E, A>

Converts a Result to a Validation. Ok becomes Passed; Err(e) becomes Failed([e]).

Useful when bridging from error-short-circuiting Result pipelines into error-accumulating Validation pipelines.

Type Parameters

E

E

A

A

Parameters

result

Result<E, A>

Returns

Validation<E, A>

Example

Validation.from.Result(Result.make.ok(42));       // Passed(42)
Validation.from.Result(Result.make.err("bad"));   // Failed(["bad"])

getOrElse

getOrElse: <B>(fallback) => <A, E>(validation) => B | A

Returns the success value or a default value if the Validation is failed. The default can be a different type, widening the result to A | B.

Type Parameters

B

B

Parameters

fallback

() => B

Returns

<A, E>(validation) => B | A

See

Validation.match to handle both the passed and failed cases.

Example

pipe(Validation.make.passed(5), Validation.getOrElse(() => 0)); // 5
pipe(Validation.make.failed("oops"), Validation.getOrElse(() => 0)); // 0
pipe(Validation.make.failed("oops"), Validation.getOrElse(() => null)); // null — typed as number | null

is

is: object

is.failed

failed: <E, A>(validation) => validation is Failed<E> = isFailed

Type guard that checks if a Validation is failed.

Type Parameters

E

E

A

A

Parameters

validation

Validation<E, A>

Returns

validation is Failed<E>

See

Validation.is.passed to check if a Validation is passed.

Example

const v = Validation.make.failed("invalid");
if (Validation.is.failed(v)) {
  console.log(v.errors); // ["invalid"]
}

is.passed

passed: <E, A>(validation) => validation is Passed<A> = isPassed

Type guard that checks if a Validation is passed.

Type Parameters

E

E

A

A

Parameters

validation

Validation<E, A>

Returns

validation is Passed<A>

See

Validation.is.failed to check if a Validation is failed.

Example

const v = Validation.make.passed(42);
if (Validation.is.passed(v)) {
  console.log(v.value); // 42
}

keyed

keyed: object

keyed.getErrors

getErrors: <T>(keyed) => Maybe<KeyedErrors<{ [K in string | number | symbol]: T[K] extends Validation<unknown, A> ? A : never }, T[keyof T] extends Validation<E, unknown> ? E : never>>

Extracts keyed field errors if any field failed. Symmetrical to getPassed: returns Some(errors) when there are failures, or None if every field passed.

Type Parameters

T

T extends Record<string, Validation<unknown, unknown>>

Parameters

keyed

T

Returns

Maybe<KeyedErrors<{ [K in string | number | symbol]: T[K] extends Validation<unknown, A> ? A : never }, T[keyof T] extends Validation<E, unknown> ? E : never>>

See

Validation.keyed.getPassed to extract keyed values when all fields pass.

Example

const errors = Validation.keyed.getErrors(results);
// Some({ name: ["Name required"] }) or None

keyed.getPassed

getPassed: <T, E>(keyed) => Maybe<T>

Extracts all validated field values if every field passed. Returns Some(data) if all passed, None if any field failed.

Type Parameters

T

T extends Record<string, unknown>

E

E

Parameters

keyed

{ readonly [K in string | number | symbol]: Validation<E, T[K]> }

Returns

Maybe<T>

See

Validation.keyed.getErrors to extract keyed field errors when failures occur.

Example

const passed = Validation.keyed.getPassed(results);
// Some({ name: "Alice", age: 30 }) or None

keyed.is

is: object

keyed.is.failed

failed: <T, E>(keyed) => boolean

Checks if at least one keyed field is Failed.

Type Parameters

T

T extends Record<string, unknown>

E

E

Parameters

keyed

{ readonly [K in string | number | symbol]: Validation<E, T[K]> }

Returns

boolean

See

Validation.keyed.is.passed to check if all keyed fields passed.

Example

if (Validation.keyed.is.failed(results)) {
  console.log("Validation errors occurred");
}

keyed.is.passed

passed: <T, E>(keyed) => keyed is { readonly [K in string | number | symbol]: Passed<T[K]> }

Type guard checking if every keyed field is Passed.

Type Parameters

T

T extends Record<string, unknown>

E

E

Parameters

keyed

{ readonly [K in string | number | symbol]: Validation<E, T[K]> }

Returns

keyed is { readonly [K in string | number | symbol]: Passed<T[K]> }

See

Validation.keyed.is.failed to check if any keyed field failed.

Example

if (Validation.keyed.is.passed(results)) {
  // results.name is Passed<string>, results.age is Passed<number>
}

keyed.make

make: <T, E>(validators) => (input) => KeyedResult<T, E>

Creates a keyed validator function from a schema of field validators. Evaluates each validator against its corresponding field in the input object, returning a record where every key holds its own Validation outcome.

Type Parameters

T

T extends Record<string, unknown>

E

E = unknown

Parameters

validators

{ readonly [K in string | number | symbol]: (val: T[K]) => Validation<E, T[K]> }

Returns

(input) => KeyedResult<T, E>

Example

const validateUser = Validation.keyed.make({
  name: (s: string) => s.length > 0 ? Validation.make.passed(s) : Validation.make.failed("Name required"),
  age: (n: number) => n >= 18 ? Validation.make.passed(n) : Validation.make.failed("Must be 18+"),
});

const result = validateUser({ name: "", age: 16 });
// { name: Failed(["Name required"]), age: Failed(["Must be 18+"]) }

make

make: object

make.failed

failed: <E>(error) => Failed<E> = makeFailed

Creates a failed Validation from a single error.

Type Parameters

E

E

Parameters

error

E

Returns

Failed<E>

Example

Validation.make.failed("Invalid input");

make.failedAll

failedAll: <E>(errors) => Failed<E> = makeFailedAll

Creates a failed Validation from multiple errors.

Type Parameters

E

E

Parameters

errors

NonEmptyArr<E>

Returns

Failed<E>

Example

Validation.make.failedAll(["Invalid input"]);

make.passed

passed: <A>(value) => Passed<A> = makePassed

Wraps a value in a passed Validation.

Type Parameters

A

A

Parameters

value

A

Returns

Passed<A>

Example

Validation.make.passed(42); // Passed(42)

map

map: <A, B>(transform) => <E>(validation) => Validation<E, B>

Transforms the success value inside a Validation.

Type Parameters

A

A

B

B

Parameters

transform

(value) => B

Returns

<E>(validation) => Validation<E, B>

See

• Validation.mapError to transform accumulated errors.
• Validation.apply to combine multiple validations.

Example

pipe(Validation.make.passed(5), Validation.map(n => n * 2)); // Passed(10)
pipe(Validation.make.failed("oops"), Validation.map(n => n * 2)); // Failed(["oops"])

mapError

mapError: <E, F>(transform) => <A>(validation) => Validation<F, A>

Transforms the error list inside a Validation.

Type Parameters

E

E

F

F

Parameters

transform

(error) => F

Returns

<A>(validation) => Validation<F, A>

See

Validation.map to transform the success value.

Example

pipe(Validation.make.failed("oops"), Validation.mapError(e => e.toUpperCase())); // Failed(["OOPS"])

match

match: <E, A, B>(cases) => (validation) => B

Pattern matches on a Validation, returning the result of the matching case.

Type Parameters

E

E

A

A

B

B

Parameters

cases

failed

(errors) => B

passed

(value) => B

Returns

(validation) => B

See

Validation.getOrElse to extract the success value with a default fallback.

Example

pipe(
  validation,
  Validation.match({
    passed: value => `Got ${value}`,
    failed: errors => `Failed: ${errors.join(", ")}`
  })
);

recover

recover: <E1, B, E2>(fallback) => <A>(validation) => Validation<E2, B | A>

Recovers from a Failed state by providing a fallback Validation. The fallback receives the accumulated error list so callers can inspect which errors occurred. The fallback can produce a different success type or resolve with a different error type.

Type Parameters

E1

E1

B

B

E2

E2 = never

Parameters

fallback

(errors) => Validation<E2, B>

Returns

<A>(validation) => Validation<E2, B | A>

See

Validation.recoverUnless to conditionally recover based on accumulated errors.

recoverUnless

recoverUnless: <E1, B, E2>(isBlocked, fallback) => <A>(validation) => Validation<E1 | E2, B | A>

Recovers from a Failed state unless isBlocked returns true for any of the accumulated errors. The fallback can produce a different success type, widening the result to Validation<E1 | E2, A | B>.

Type Parameters

E1

E1

B

B

E2

E2 = never

Parameters

isBlocked

(error) => boolean

fallback

(errors) => Validation<E2, B>

Returns

<A>(validation) => Validation<E1 | E2, B | A>

See

Validation.recover for unconditional error recovery.

Example

pipe(
  Validation.make.failed("field-error"),
  Validation.recoverUnless(e => e === "fatal", () => Validation.make.passed(0))
); // Passed(0)

struct

struct: <T>(fields) => Validation<T[keyof T] extends Validation<E, unknown> ? E : never, { [K in string | number | symbol]: T[K] extends Validation<unknown, A> ? A : never }>

Combines a record of Validations into a single Validation of a record. Accumulates all failed branches’ errors.

Type Parameters

T

T extends Record<string, Validation<unknown, unknown>>

Parameters

fields

T

Returns

Validation<T[keyof T] extends Validation<E, unknown> ? E : never, { [K in string | number | symbol]: T[K] extends Validation<unknown, A> ? A : never }>

Example

Validation.struct({
  name: Validation.make.passed("Alice"),
  age: Validation.make.passed(30)
}); // Passed({ name: "Alice", age: 30 })

Validation.struct({
  name: Validation.make.failed("Name required"),
  age: Validation.make.failed("Age must be >= 0")
}); // Failed(["Name required", "Age must be >= 0"])

tap

tap: <A>(sideEffect) => <E>(validation) => Validation<E, A>

Executes a side effect on the success value without changing the Validation.

Type Parameters

A

A

Parameters

sideEffect

(value) => void

Returns

<E>(validation) => Validation<E, A>

See

Validation.tapError to perform a side effect on accumulated errors.

Example

pipe(
  Validation.make.passed(5),
  Validation.tap(n => console.log("Value:", n)),
  Validation.map(n => n * 2)
);

tapError

tapError: <E>(sideEffect) => <A>(validation) => Validation<E, A>

Executes a side effect on the accumulated errors without changing the Validation. Useful for logging or reporting validation failures.

Type Parameters

E

E

Parameters

sideEffect

(errors) => void

Returns

<A>(validation) => Validation<E, A>

See

Validation.tap to perform a side effect on the success value.

Example

pipe(
  Validation.make.failed("Name required"),
  Validation.tapError(errors => console.error("validation failed:", errors)),
  Validation.map(toUser)
);

to

to: object

to.Maybe

Maybe: <E, A>(validation) => Maybe<A>

Converts a Validation to a Maybe. Passed becomes Some; Failed becomes None (errors are discarded).

Type Parameters

E

E

A

A

Parameters

validation

Validation<E, A>

Returns

Maybe<A>

Example

Validation.to.Maybe(Validation.make.passed(42));       // Some(42)
Validation.to.Maybe(Validation.make.failed("bad"));  // None

to.Result

Result: {<E1, E2, A>(combineErrors): (validation) => Result<E2, A>; <E, A>(validation): Result<NonEmptyArr<E>, A>; } = toResult

Converts a Validation to a Result. Passed becomes Ok. Direct call converts Failed to Err with accumulated error list NonEmptyArr<E>. Curried call converts Failed to Err with combined error E2 via combineErrors.

Call Signature

<E1, E2, A>(combineErrors): (validation) => Result<E2, A>

Type Parameters

E1

E1

E2

E2

A

A

Parameters

combineErrors

(errors) => E2

Returns

(validation) => Result<E2, A>

Call Signature

<E, A>(validation): Result<NonEmptyArr<E>, A>

Type Parameters

E

E

A

A

Parameters

validation

Validation<E, A>

Returns

Result<NonEmptyArr<E>, A>

Example

Validation.to.Result(Validation.make.passed(42));        // Ok(42)
Validation.to.Result(Validation.make.failed("oops"));  // Err(["oops"])
pipe(Validation.make.failed("oops"), Validation.to.Result(errors => errors.join(", "))); // Err("oops")

tryCatch

tryCatch: <E, A>(fn, options) => Validation<E, A>

Creates a Validation from a synchronous thunk that may throw. Catches any errors and transforms them using the onError function into a Failed validation.

Type Parameters

E

E

A

A

Parameters

fn

() => A

options

onError

(error) => E

Returns

Validation<E, A>

Example

const result = Validation.tryCatch(
  () => JSON.parse(rawString),
  { onError: (error) => `Parse error: ${error}` }
);