ConstraintModule

PackageReified.Constraint
Creates, executes, composes, and inspects constraints.

Summary

NameSignatureSynopsis
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.

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

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

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

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

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 ]

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 ]

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" ])

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

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

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

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))

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)

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."

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

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

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)

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

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

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

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

single

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

Returns

Constraint<^value>

Verification Examples

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

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

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

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

emailPattern

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

Returns

string

numericPattern

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

Returns

string

nonBlankPattern

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

Returns

string

trimmedPattern

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

Returns

string

email

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

Returns

Constraint<string>

Verification Examples

let contact : Constraint<string> = Constraint.email

trimmed

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

Returns

Constraint<string>

Verification Examples

let slug : Constraint<string> = Constraint.trimmed

numeric

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

Returns

Constraint<string>

Verification Examples

let pin : Constraint<string> = Constraint.numeric

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

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}$"

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>

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>

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>

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>

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

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

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"

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

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

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

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

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

positive

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

Returns

Constraint<^value>

Verification Examples

let quantity : Constraint<int> = Constraint.positive

nonNegative

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

Returns

Constraint<^value>

Verification Examples

let balance : Constraint<decimal> = Constraint.nonNegative

negative

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

Returns

Constraint<^value>

Verification Examples

let adjustment : Constraint<int> = Constraint.negative

nonPositive

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

Returns

Constraint<^value>

Verification Examples

let drawdown : Constraint<int> = Constraint.nonPositive

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" ]

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" ]

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>

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>

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>

containsIn

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

Parameters

NameTypeDescription
expected'value
values'a

Returns

bool

excludesIn

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

Parameters

NameTypeDescription
expected'value
values'a

Returns

bool

firstDuplicate

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

Parameters

NameTypeDescription
values'a

Returns

'value option

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"

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"

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

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>

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

finite

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

Returns

Constraint<float>

Verification Examples

let ratio : Constraint<float> = Constraint.finite

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