Constraints

A constraint lets you define a rule that typing alone cannot check. For example, a constraint can verify that a string matches a particular format (email, URL, …), or that a number is within a certain range. A constraint applies to a primitive.

How it works

A constraint is created from:

• a primitive (e.g. C.String, C.Number)
• one or more DDataParser checkers (DP.checkerEmail(), DP.checkerInt(), ...)

At runtime, a constraint validates the value, then adds an internal marking (by constraint name). On the TypeScript side, this marking is reflected in the type: you can then write functions that accept “any value carrying this constraint”, whether it is a constrained primitive or a NewType that embeds the same constraint.

Example

Constraints sets

When you need to apply several constraints together, you can build a reusable set with C.createConstraintsSet(...).

Create a constraint

To create a constraint, use C.createConstraint(name, primitive, checker) then get its type via C.GetConstraint.

This type (e.g. SlugConstraint) is then used:

• as a “contract” (e.g. function parameter)
• as a constraint to apply when creating a NewType (C.createNewType(..., SlugConstraint))

Methods and Properties

A constraint is a handler (like a primitive). It therefore exposes creation/validation methods and a few properties.

Methods

create()

function create(
	value: RawType | Primitive<RawType>
): Right<ConstrainedType<ConstraintName, RawType>> | Left<DP.DataParserError>

createOrThrow()

function createOrThrow(
	value: RawType | Primitive<RawType>
): ConstrainedType<ConstraintName, RawType>

Throws C.CreateConstrainedTypeError if validation fails.

createWithUnknown()

function createWithUnknown(
	value: unknown
): Right<ConstrainedType<ConstraintName, RawType>> | Left<DP.DataParserError>

createWithUnknownOrThrow()

function createWithUnknownOrThrow(
	value: unknown
): ConstrainedType<ConstraintName, RawType>

Throws C.CreateConstrainedTypeError if validation fails.

is()

function is(
	value: unknown
): value is ConstrainedType<ConstraintName, RawType>

Properties

name

The unique name of the constraint (e.g. "email", "int", ...).

checkers

The list of DDataParser checkers used to validate the value.

primitiveHandler

The primitive to which the constraint applies (e.g. C.String, C.Number).

Constraints provided by the library

The library exports a few ready-to-use constraints via C.*:

Email

Validates a string in email format.

Url

Validates a string in URL format.

StringMin

Validates a string with a minimum length (>= min).

StringMax

Validates a string with a maximum length (<= max).

Int

Validates an integer.

Positive

Validates a strictly positive number (>= 1).

PositiveInt

Validates a strictly positive integer (>= 1).

Negative

Validates a strictly negative number (<= -1).

NumberMin

Validates a number greater than or equal to min.

NumberMax

Validates a number less than or equal to max.

PositiveTime

Validates a strictly positive duration (>= 1 millisecond) on the C.Time primitive.

NegativeTime

Validates a strictly negative duration (<= -1 millisecond) on the C.Time primitive.

See also

• Primitives
• NewType