ConstraintModule

Creates, executes, composes, and inspects constraints.

Summary

NameSignatureSynopsis
Operations
satisfiesConstraint.satisfies constraint' valueAnswers whether a value satisfies a constraint, without building a violation.
checkConstraint.check constraint' valueRuns a constraint, returning why the value failed.
guardConstraint.guard constraint' valueRuns a constraint and returns the unchanged value after success.
inspectConstraint.inspect constraint'Returns the constraint's inspectable description.
allConstraint.all constraintsRequires every constraint to hold, evaluating each in declaration order and accumulating failures.
anyConstraint.any first restRequires at least one alternative to hold, evaluating left to right and stopping at the first success.
notWithConstraint.notWith description constraint'Negates a constraint.
customConstraint.custom description predicateRuns an arbitrary predicate, reporting the supplied prose when it fails.
customLocalizedConstraint.customLocalized key description predicateRuns an arbitrary predicate, reporting the supplied prose and the author's own catalogue key when it fails.
customLocalizedWithConstraint.customLocalizedWith key description arguments predicateRuns an arbitrary predicate, reporting the supplied prose plus a catalogue key and named arguments a translation can interpolate.
customWithConstraint.customWith description checkRuns an arbitrary callback that reports its own violation.
contramapConstraint.contramap project constraint'Applies a constraint to a projection of a larger value.
describeConstraint.describe description constraint'Attaches documentary prose to a constraint.
presentConstraint.present Requires a value to be inhabited according to its shape.
blankConstraint.blank Requires a value to be uninhabited according to its shape; the exact complement of present.
optionalConstraint.optional innerLifts a constraint over an optional container: absence passes, presence runs the inner constraint.
lengthConstraint.length expectedRequires text or a collection to have exactly the supplied size.
minLengthConstraint.minLength minimumRequires text or a collection to have at least the supplied size.
maxLengthConstraint.maxLength maximumRequires text or a collection to have at most the supplied size.
lengthBetweenConstraint.lengthBetween minimum maximumRequires a text or collection size inside the supplied inclusive bounds.
singleConstraint.single Requires a collection to hold exactly one item.
atLeastOneConstraint.atLeastOne Requires a collection to hold at least one item.
atMostOneConstraint.atMostOne Requires a collection to hold no more than one item.
moreThanOneConstraint.moreThanOne Requires a collection to hold two or more items.
emailPatternConstraint.emailPattern The exact regular expression Constraint.email runs.
numericPatternConstraint.numericPattern The exact regular expression Constraint.numeric runs.
nonBlankPatternConstraint.nonBlankPattern The regular expression an exporter may publish for Constraint.present on text.
trimmedPatternConstraint.trimmedPattern The regular expression an exporter may publish for Constraint.trimmed.
emailConstraint.email Requires text to match Reified's pragmatic email shape, ^[^@]+@[^@]+$.
trimmedConstraint.trimmed Requires text to have no leading or trailing whitespace.
numericConstraint.numeric Requires text to be one or more ASCII digits.
alphanumericConstraint.alphanumeric Requires text to be one or more letters or digits.
patternConstraint.pattern expressionRequires text to match the supplied .NET regular expression.
relationWithConstraint.relationWith operator expected actual predicateBuilds a relation from an already-projected operand.
withinWithConstraint.withinWith minimum maximum actual predicateBuilds an inclusive range from already-projected bounds.
oneOfWithConstraint.oneOfWith choices actual predicateBuilds a membership rule from already-projected choices.
noneOfWithConstraint.noneOfWith choices actual predicateBuilds an exclusion rule from already-projected choices.
checkBoundsConstraint.checkBounds name minimum maximumValidates inclusive bounds.
equalToConstraint.equalTo expectedRequires equality with the supplied value, under F# structural equality.
notEqualToConstraint.notEqualTo unexpectedRequires inequality with the supplied value, under F# structural equality.
greaterThanConstraint.greaterThan minimumRequires a value strictly greater than the supplied bound.
lessThanConstraint.lessThan maximumRequires a value strictly less than the supplied bound.
atLeastConstraint.atLeast minimumRequires a value greater than or equal to the supplied bound.
atMostConstraint.atMost maximumRequires a value less than or equal to the supplied bound.
betweenConstraint.between minimum maximumRequires a value inside the supplied inclusive bounds.
positiveConstraint.positive Requires a value strictly greater than zero.
nonNegativeConstraint.nonNegative Requires a value of zero or greater.
negativeConstraint.negative Requires a value strictly less than zero.
nonPositiveConstraint.nonPositive Requires a value of zero or less.
oneOfConstraint.oneOf choicesRequires the value to equal one of the supplied choices.
noneOfConstraint.noneOf choicesRequires the value to equal none of the supplied choices.
containsWithConstraint.containsWith expected valuesBuilds a containment rule from an already-projected item.
notContainsWithConstraint.notContainsWith expected valuesBuilds an exclusion rule from an already-projected item.
uniquenessWithConstraint.uniquenessWith item duplicateBuilds a uniqueness rule with a caller-supplied item projection.
containsInConstraint.containsIn expected valuesThe containment predicate.
excludesInConstraint.excludesIn expected valuesThe exclusion predicate.
firstDuplicateConstraint.firstDuplicate valuesThe first-duplicate projection.
containsConstraint.contains expectedRequires a collection to contain the supplied item.
notContainsConstraint.notContains expectedRequires a collection not to contain the supplied item.
distinctConstraint.distinct Requires a collection to hold no duplicates.
multipleOfWithConstraint.multipleOfWith divisor actual predicateBuilds a divisibility rule from an already-projected divisor.
multipleOfConstraint.multipleOf divisorRequires an exact multiple of the supplied divisor, under the value type's own arithmetic.
finiteConstraint.finite Requires a double to be neither infinite nor NaN.
finite32Constraint.finite32 Requires a single-precision float to be neither infinite nor NaN.

Operations

kind:member

satisfies

Constraint.satisfies constraint' value
Member
Answers whether a value satisfies a constraint, without building a violation.

Parameters

NameTypeDescription
constraint'Constraint<'value>
value'value

Returns

bool

Verification Examples

let retryCount = Constraint.between 0 10
 3 |> Constraint.satisfies retryCount // true
kind:member

check

Constraint.check constraint' value
Member
Runs a constraint, returning why the value failed.

Parameters

NameTypeDescription
constraint'Constraint<'value>
value'value

Returns

Result<unit, Violation>

Verification Examples

let retryCount = Constraint.between 0 10
 42 |> Constraint.check retryCount |> Result.mapError Violation.render
kind:member

guard

Constraint.guard constraint' value
Member
Runs a constraint and returns the unchanged value after success.

Parameters

NameTypeDescription
constraint'Constraint<'value>
value'value

Returns

Result<'value, Violation>

Verification Examples

let requiredName : Constraint<string> = Constraint.present
 "Alice" |> Constraint.guard requiredName |> Result.mapError Violation.render
kind:member

inspect

Constraint.inspect constraint'
Member
Returns the constraint's inspectable description.

Parameters

NameTypeDescription
constraint'Constraint<'value>

Returns

ConstraintDescription

Verification Examples

let requiredName : Constraint<string> = Constraint.present
 (Constraint.inspect requiredName).Expression
kind:member

all

Constraint.all constraints
Member
Requires every constraint to hold, evaluating each in declaration order and accumulating failures. The empty list is the satisfied identity.

Parameters

NameTypeDescription
constraintsConstraint<'value> list

Returns

Constraint<'value>

Verification Examples

let requiredName : Constraint<string> =
     Constraint.all [ Constraint.present; Constraint.lengthBetween 2 40 ]
kind:member

any

Constraint.any first rest
Member
Requires at least one alternative to hold, evaluating left to right and stopping at the first success. When none succeeds, every rejected branch is reported.

Parameters

NameTypeDescription
firstConstraint<'value>
restConstraint<'value> list

Returns

Constraint<'value>

Verification Examples

let ttl : Constraint<int> =
     Constraint.any (Constraint.equalTo -1) [ Constraint.atLeast 1 ]
kind:member

notWith

Constraint.notWith description constraint'
Member
Negates a constraint. The result is opaque: it runs normally but cannot be exported or proved, and reports the supplied prose.

Parameters

NameTypeDescription
descriptionstring
constraint'Constraint<'value>

Returns

Constraint<'value>

Verification Examples

Constraint.notWith "must not be a reserved name" (Constraint.oneOf [ "admin"; "root" ])
kind:member

custom

Constraint.custom description predicate
Member
Runs an arbitrary predicate, reporting the supplied prose when it fails.

Parameters

NameTypeDescription
descriptionstring
predicate'value -> bool

Returns

Constraint<'value>

Verification Examples

let isValidIsbn (isbn: string) = isbn.Length = 13 in Constraint.custom "must be a valid ISBN" isValidIsbn
kind:member

customLocalized

Constraint.customLocalized key description predicate
Member
Runs an arbitrary predicate, reporting the supplied prose and the author's own catalogue key when it fails.

Parameters

NameTypeDescription
keystring
descriptionstring
predicate'value -> bool

Returns

Constraint<'value>

Verification Examples

let isValidIsbn (isbn: string) = isbn.Length = 13
 in Constraint.customLocalized
     "books.isbn.invalid"
     "must be a valid ISBN"
     isValidIsbn
kind:member

customLocalizedWith

Constraint.customLocalizedWith key description arguments predicate
Member
Runs an arbitrary predicate, reporting the supplied prose plus a catalogue key and named arguments a translation can interpolate.

Parameters

NameTypeDescription
keystring
descriptionstring
argumentsMap<string, ConstraintValue>
predicate'value -> bool

Returns

Constraint<'value>

Verification Examples

let isValidIsbn (isbn: string) = isbn.Length = 13
 in Constraint.customLocalizedWith
     "books.isbn.invalid"
     "must be a valid ISBN"
     (Map.ofList [ "expectedLength", ConstraintValue.Integer 13L ])
     isValidIsbn
kind:member

customWith

Constraint.customWith description check
Member
Runs an arbitrary callback that reports its own violation.

Parameters

NameTypeDescription
descriptionstring
check'value -> Result<unit, Violation>

Returns

Constraint<'value>

Verification Examples

let supported = [ "USD"; "EUR" ] in Constraint.customWith "must be a supported currency" (Constraint.check (Constraint.oneOf supported))
kind:member

contramap

Constraint.contramap project constraint'
Member
Applies a constraint to a projection of a larger value.

Parameters

NameTypeDescription
project'input -> 'value
constraint'Constraint<'value>

Returns

Constraint<'input>

Verification Examples

Constraint.present |> Constraint.contramap (fun order -> order.Reference)
kind:member

describe

Constraint.describe description constraint'
Member
Attaches documentary prose to a constraint.

Parameters

NameTypeDescription
descriptionstring
constraint'Constraint<'value>

Returns

Constraint<'value>

Verification Examples

Constraint.between 0 10 |> Constraint.describe "Retries before the call is abandoned."
kind:member

present

Constraint.present
Member
Requires a value to be inhabited according to its shape.

Returns

Constraint<^value>

Verification Examples

let requiredName : Constraint<string> = Constraint.present
kind:member

blank

Constraint.blank
Member
Requires a value to be uninhabited according to its shape; the exact complement of present.

Returns

Constraint<^value>

Verification Examples

let mustBeUnset : Constraint<string> = Constraint.blank
kind:member

optional

Constraint.optional inner
Member
Lifts a constraint over an optional container: absence passes, presence runs the inner constraint.

Parameters

NameTypeDescription
innerConstraint<'value>

Returns

Constraint<^container>

Verification Examples

let nickname : Constraint<string option> =
     Constraint.optional (Constraint.lengthBetween 2 40)
kind:member

length

Constraint.length expected
Member
Requires text or a collection to have exactly the supplied size.

Parameters

NameTypeDescription
expectedint

Returns

Constraint<^value>

Verification Examples

let code : Constraint<string> = Constraint.length 6
kind:member

minLength

Constraint.minLength minimum
Member
Requires text or a collection to have at least the supplied size.

Parameters

NameTypeDescription
minimumint

Returns

Constraint<^value>

Verification Examples

let tags : Constraint<string list> = Constraint.minLength 1
kind:member

maxLength

Constraint.maxLength maximum
Member
Requires text or a collection to have at most the supplied size.

Parameters

NameTypeDescription
maximumint

Returns

Constraint<^value>

Verification Examples

let summary : Constraint<string> = Constraint.maxLength 280
kind:member

lengthBetween

Constraint.lengthBetween minimum maximum
Member
Requires a text or collection size inside the supplied inclusive bounds.

Parameters

NameTypeDescription
minimumint
maximumint

Returns

Constraint<^value>

Verification Examples

let name : Constraint<string> = Constraint.lengthBetween 2 40
kind:member

single

Constraint.single
Member
Requires a collection to hold exactly one item.

Returns

Constraint<^value>

Verification Examples

let primaryAddress : Constraint<Address list> = Constraint.single
kind:member

atLeastOne

Constraint.atLeastOne
Member
Requires a collection to hold at least one item.

Returns

Constraint<^value>

Verification Examples

let tags : Constraint<string list> = Constraint.atLeastOne
kind:member

atMostOne

Constraint.atMostOne
Member
Requires a collection to hold no more than one item.

Returns

Constraint<^value>

Verification Examples

let overrides : Constraint<Rule list> = Constraint.atMostOne
kind:member

moreThanOne

Constraint.moreThanOne
Member
Requires a collection to hold two or more items.

Returns

Constraint<^value>

Verification Examples

let participants : Constraint<Party list> = Constraint.moreThanOne
kind:member

emailPattern

Constraint.emailPattern
Member
The exact regular expression Constraint.email runs.

Returns

string
kind:member

numericPattern

Constraint.numericPattern
Member
The exact regular expression Constraint.numeric runs.

Returns

string
kind:member

nonBlankPattern

Constraint.nonBlankPattern
Member
The regular expression an exporter may publish for Constraint.present on text.

Returns

string
kind:member

trimmedPattern

Constraint.trimmedPattern
Member
The regular expression an exporter may publish for Constraint.trimmed.

Returns

string
kind:member

email

Constraint.email
Member
Requires text to match Reified's pragmatic email shape, ^[^@]+@[^@]+$.

Returns

Constraint<string>

Verification Examples

let contact : Constraint<string> = Constraint.email
kind:member

trimmed

Constraint.trimmed
Member
Requires text to have no leading or trailing whitespace.

Returns

Constraint<string>

Verification Examples

let slug : Constraint<string> = Constraint.trimmed
kind:member

numeric

Constraint.numeric
Member
Requires text to be one or more ASCII digits.

Returns

Constraint<string>

Verification Examples

let pin : Constraint<string> = Constraint.numeric
kind:member

alphanumeric

Constraint.alphanumeric
Member
Requires text to be one or more letters or digits.

Returns

Constraint<string>

Verification Examples

let handle : Constraint<string> = Constraint.alphanumeric
kind:member

pattern

Constraint.pattern expression
Member
Requires text to match the supplied .NET regular expression.

Parameters

NameTypeDescription
expressionstring

Returns

Constraint<string>

Verification Examples

let reference : Constraint<string> = Constraint.pattern @"^[A-Z]{3}-\d{4}$"
kind:member

relationWith

Constraint.relationWith operator expected actual predicate
Member
Builds a relation from an already-projected operand. Not part of the supported surface.

Parameters

NameTypeDescription
operatorRelationOperator
expectedConstraintValue option
actual'value -> ConstraintValue option
predicate'value -> bool

Returns

Constraint<'value>
kind:member

withinWith

Constraint.withinWith minimum maximum actual predicate
Member
Builds an inclusive range from already-projected bounds. Not part of the supported surface.

Parameters

NameTypeDescription
minimumConstraintValue option
maximumConstraintValue option
actual'value -> ConstraintValue option
predicate'value -> bool

Returns

Constraint<'value>
kind:member

oneOfWith

Constraint.oneOfWith choices actual predicate
Member
Builds a membership rule from already-projected choices. Not part of the supported surface.

Parameters

NameTypeDescription
choicesConstraintValue option list
actual'value -> ConstraintValue option
predicate'value -> bool

Returns

Constraint<'value>
kind:member

noneOfWith

Constraint.noneOfWith choices actual predicate
Member
Builds an exclusion rule from already-projected choices. Not part of the supported surface.

Parameters

NameTypeDescription
choicesConstraintValue option list
actual'value -> ConstraintValue option
predicate'value -> bool

Returns

Constraint<'value>
kind:member

checkBounds

Constraint.checkBounds name minimum maximum
Member
Validates inclusive bounds. Not part of the supported surface.

Parameters

NameTypeDescription
namestring
minimum'a
maximum'a

Returns

unit
kind:member

equalTo

Constraint.equalTo expected
Member
Requires equality with the supplied value, under F# structural equality.

Parameters

NameTypeDescription
expected'value

Returns

Constraint<'value>

Verification Examples

let mustBeDraft : Constraint<Status> = Constraint.equalTo Status.Draft
kind:member

notEqualTo

Constraint.notEqualTo unexpected
Member
Requires inequality with the supplied value, under F# structural equality.

Parameters

NameTypeDescription
unexpected'value

Returns

Constraint<'value>

Verification Examples

let notReserved : Constraint<string> = Constraint.notEqualTo "admin"
kind:member

greaterThan

Constraint.greaterThan minimum
Member
Requires a value strictly greater than the supplied bound.

Parameters

NameTypeDescription
minimum'value

Returns

Constraint<'value>

Verification Examples

let quantity : Constraint<int> = Constraint.greaterThan 0
kind:member

lessThan

Constraint.lessThan maximum
Member
Requires a value strictly less than the supplied bound.

Parameters

NameTypeDescription
maximum'value

Returns

Constraint<'value>

Verification Examples

let discount : Constraint<decimal> = Constraint.lessThan 1.0M
kind:member

atLeast

Constraint.atLeast minimum
Member
Requires a value greater than or equal to the supplied bound.

Parameters

NameTypeDescription
minimum'value

Returns

Constraint<'value>

Verification Examples

let age : Constraint<int> = Constraint.atLeast 13
kind:member

atMost

Constraint.atMost maximum
Member
Requires a value less than or equal to the supplied bound.

Parameters

NameTypeDescription
maximum'value

Returns

Constraint<'value>

Verification Examples

let weight : Constraint<int> = Constraint.atMost 100
kind:member

between

Constraint.between minimum maximum
Member
Requires a value inside the supplied inclusive bounds.

Parameters

NameTypeDescription
minimum'value
maximum'value

Returns

Constraint<'value>

Verification Examples

let retryCount : Constraint<int> = Constraint.between 0 10
kind:member

positive

Constraint.positive
Member
Requires a value strictly greater than zero.

Returns

Constraint<^value>

Verification Examples

let quantity : Constraint<int> = Constraint.positive
kind:member

nonNegative

Constraint.nonNegative
Member
Requires a value of zero or greater.

Returns

Constraint<^value>

Verification Examples

let balance : Constraint<decimal> = Constraint.nonNegative
kind:member

negative

Constraint.negative
Member
Requires a value strictly less than zero.

Returns

Constraint<^value>

Verification Examples

let adjustment : Constraint<int> = Constraint.negative
kind:member

nonPositive

Constraint.nonPositive
Member
Requires a value of zero or less.

Returns

Constraint<^value>

Verification Examples

let drawdown : Constraint<int> = Constraint.nonPositive
kind:member

oneOf

Constraint.oneOf choices
Member
Requires the value to equal one of the supplied choices.

Parameters

NameTypeDescription
choices'value seq

Returns

Constraint<'value>

Verification Examples

let currency : Constraint<string> = Constraint.oneOf [ "AUD"; "NZD" ]
kind:member

noneOf

Constraint.noneOf choices
Member
Requires the value to equal none of the supplied choices.

Parameters

NameTypeDescription
choices'value seq

Returns

Constraint<'value>

Verification Examples

let handle : Constraint<string> = Constraint.noneOf [ "admin"; "root" ]
kind:member

containsWith

Constraint.containsWith expected values
Member
Builds a containment rule from an already-projected item. Not part of the supported surface.

Parameters

NameTypeDescription
expectedConstraintValue option
values'a -> bool

Returns

Constraint<'a>
kind:member

notContainsWith

Constraint.notContainsWith expected values
Member
Builds an exclusion rule from an already-projected item. Not part of the supported surface.

Parameters

NameTypeDescription
expectedConstraintValue option
values'a -> bool

Returns

Constraint<'a>
kind:member

uniquenessWith

Constraint.uniquenessWith item duplicate
Member
Builds a uniqueness rule with a caller-supplied item projection. Not part of the supported surface.

Parameters

NameTypeDescription
item'value -> ConstraintValue option
duplicate'a -> 'value option

Returns

Constraint<'a>
kind:member

containsIn

Constraint.containsIn expected values
Member
The containment predicate. Not part of the supported surface.

Parameters

NameTypeDescription
expected'value
values'a

Returns

bool
kind:member

excludesIn

Constraint.excludesIn expected values
Member
The exclusion predicate. Not part of the supported surface.

Parameters

NameTypeDescription
expected'value
values'a

Returns

bool
kind:member

firstDuplicate

Constraint.firstDuplicate values
Member
The first-duplicate projection. Not part of the supported surface.

Parameters

NameTypeDescription
values'a

Returns

'value option
kind:member

contains

Constraint.contains expected
Member
Requires a collection to contain the supplied item.

Parameters

NameTypeDescription
expected'value

Returns

Constraint<^container>

Verification Examples

let mustIncludeAdmin : Constraint<string list> = Constraint.contains "admin"
kind:member

notContains

Constraint.notContains expected
Member
Requires a collection not to contain the supplied item.

Parameters

NameTypeDescription
expected'value

Returns

Constraint<^container>

Verification Examples

let tags : Constraint<string list> = Constraint.notContains "internal"
kind:member

distinct

Constraint.distinct
Member
Requires a collection to hold no duplicates. The first repeat is reported as the actual value.

Returns

Constraint<^container>

Verification Examples

let tags : Constraint<string list> = Constraint.distinct
kind:member

multipleOfWith

Constraint.multipleOfWith divisor actual predicate
Member
Builds a divisibility rule from an already-projected divisor. Not part of the supported surface.

Parameters

NameTypeDescription
divisorConstraintValue option
actual'value -> ConstraintValue option
predicate'value -> bool

Returns

Constraint<'value>
kind:member

multipleOf

Constraint.multipleOf divisor
Member
Requires an exact multiple of the supplied divisor, under the value type's own arithmetic.

Parameters

NameTypeDescription
divisor^value

Returns

Constraint<^value>

Verification Examples

let batchSize : Constraint<int> = Constraint.multipleOf 10
kind:member

finite

Constraint.finite
Member
Requires a double to be neither infinite nor NaN.

Returns

Constraint<float>

Verification Examples

let ratio : Constraint<float> = Constraint.finite
kind:member

finite32

Constraint.finite32
Member
Requires a single-precision float to be neither infinite nor NaN.

Returns

Constraint<float32>

Verification Examples

let ratio : Constraint<float32> = Constraint.finite32