ConstraintModule
PackageReified.Constraint
Creates, executes, composes, and inspects constraints.
Summary
| Name | Signature | Synopsis |
|---|---|---|
| satisfies | Constraint.satisfies constraint' value | Answers whether a value satisfies a constraint, without building a violation. |
| check | Constraint.check constraint' value | Runs a constraint, returning why the value failed. |
| guard | Constraint.guard constraint' value | Runs a constraint and returns the unchanged value after success. |
| inspect | Constraint.inspect constraint' | Returns the constraint's inspectable description. |
| all | Constraint.all constraints | Requires every constraint to hold, evaluating each in declaration order and accumulating failures. |
| any | Constraint.any first rest | Requires at least one alternative to hold, evaluating left to right and stopping at the first success. |
| notWith | Constraint.notWith description constraint' | Negates a constraint. |
| custom | Constraint.custom description predicate | Runs an arbitrary predicate, reporting the supplied prose when it fails. |
| customLocalized | Constraint.customLocalized key description predicate | Runs an arbitrary predicate, reporting the supplied prose and the author's own catalogue key when it fails. |
| customLocalizedWith | Constraint.customLocalizedWith key description arguments predicate | Runs an arbitrary predicate, reporting the supplied prose plus a catalogue key and named arguments a translation can interpolate. |
| customWith | Constraint.customWith description check | Runs an arbitrary callback that reports its own violation. |
| contramap | Constraint.contramap project constraint' | Applies a constraint to a projection of a larger value. |
| describe | Constraint.describe description constraint' | Attaches documentary prose to a constraint. |
| present | Constraint.present | Requires a value to be inhabited according to its shape. |
| blank | Constraint.blank | Requires a value to be uninhabited according to its shape; the exact complement of present. |
| optional | Constraint.optional inner | Lifts a constraint over an optional container: absence passes, presence runs the inner constraint. |
| length | Constraint.length expected | Requires text or a collection to have exactly the supplied size. |
| minLength | Constraint.minLength minimum | Requires text or a collection to have at least the supplied size. |
| maxLength | Constraint.maxLength maximum | Requires text or a collection to have at most the supplied size. |
| lengthBetween | Constraint.lengthBetween minimum maximum | Requires a text or collection size inside the supplied inclusive bounds. |
| single | Constraint.single | Requires a collection to hold exactly one item. |
| atLeastOne | Constraint.atLeastOne | Requires a collection to hold at least one item. |
| atMostOne | Constraint.atMostOne | Requires a collection to hold no more than one item. |
| moreThanOne | Constraint.moreThanOne | Requires a collection to hold two or more items. |
| emailPattern | Constraint.emailPattern | The exact regular expression Constraint.email runs. |
| numericPattern | Constraint.numericPattern | The exact regular expression Constraint.numeric runs. |
| nonBlankPattern | Constraint.nonBlankPattern | The regular expression an exporter may publish for Constraint.present on text. |
| trimmedPattern | Constraint.trimmedPattern | The regular expression an exporter may publish for Constraint.trimmed. |
| Constraint.email | Requires text to match Reified's pragmatic email shape, ^[^@]+@[^@]+$. | |
| trimmed | Constraint.trimmed | Requires text to have no leading or trailing whitespace. |
| numeric | Constraint.numeric | Requires text to be one or more ASCII digits. |
| alphanumeric | Constraint.alphanumeric | Requires text to be one or more letters or digits. |
| pattern | Constraint.pattern expression | Requires text to match the supplied .NET regular expression. |
| relationWith | Constraint.relationWith operator expected actual predicate | Builds a relation from an already-projected operand. |
| withinWith | Constraint.withinWith minimum maximum actual predicate | Builds an inclusive range from already-projected bounds. |
| oneOfWith | Constraint.oneOfWith choices actual predicate | Builds a membership rule from already-projected choices. |
| noneOfWith | Constraint.noneOfWith choices actual predicate | Builds an exclusion rule from already-projected choices. |
| checkBounds | Constraint.checkBounds name minimum maximum | Validates inclusive bounds. |
| equalTo | Constraint.equalTo expected | Requires equality with the supplied value, under F# structural equality. |
| notEqualTo | Constraint.notEqualTo unexpected | Requires inequality with the supplied value, under F# structural equality. |
| greaterThan | Constraint.greaterThan minimum | Requires a value strictly greater than the supplied bound. |
| lessThan | Constraint.lessThan maximum | Requires a value strictly less than the supplied bound. |
| atLeast | Constraint.atLeast minimum | Requires a value greater than or equal to the supplied bound. |
| atMost | Constraint.atMost maximum | Requires a value less than or equal to the supplied bound. |
| between | Constraint.between minimum maximum | Requires a value inside the supplied inclusive bounds. |
| positive | Constraint.positive | Requires a value strictly greater than zero. |
| nonNegative | Constraint.nonNegative | Requires a value of zero or greater. |
| negative | Constraint.negative | Requires a value strictly less than zero. |
| nonPositive | Constraint.nonPositive | Requires a value of zero or less. |
| oneOf | Constraint.oneOf choices | Requires the value to equal one of the supplied choices. |
| noneOf | Constraint.noneOf choices | Requires the value to equal none of the supplied choices. |
| containsWith | Constraint.containsWith expected values | Builds a containment rule from an already-projected item. |
| notContainsWith | Constraint.notContainsWith expected values | Builds an exclusion rule from an already-projected item. |
| uniquenessWith | Constraint.uniquenessWith item duplicate | Builds a uniqueness rule with a caller-supplied item projection. |
| containsIn | Constraint.containsIn expected values | The containment predicate. |
| excludesIn | Constraint.excludesIn expected values | The exclusion predicate. |
| firstDuplicate | Constraint.firstDuplicate values | The first-duplicate projection. |
| contains | Constraint.contains expected | Requires a collection to contain the supplied item. |
| notContains | Constraint.notContains expected | Requires a collection not to contain the supplied item. |
| distinct | Constraint.distinct | Requires a collection to hold no duplicates. |
| multipleOfWith | Constraint.multipleOfWith divisor actual predicate | Builds a divisibility rule from an already-projected divisor. |
| multipleOf | Constraint.multipleOf divisor | Requires an exact multiple of the supplied divisor, under the value type's own arithmetic. |
| finite | Constraint.finite | Requires a double to be neither infinite nor NaN. |
| finite32 | Constraint.finite32 | Requires a single-precision float to be neither infinite nor NaN. |
Answers whether a value satisfies a constraint, without building a violation.
Parameters
| Name | Type | Description |
|---|---|---|
| constraint' | Constraint<'value> | |
| value | 'value |
Returns
bool
Verification Examples
let retryCount = Constraint.between 0 10
3 |> Constraint.satisfies retryCount // trueRuns a constraint, returning why the value failed.
Parameters
| Name | Type | Description |
|---|---|---|
| constraint' | Constraint<'value> | |
| value | 'value |
Returns
Result<unit, Violation>
Verification Examples
let retryCount = Constraint.between 0 10
42 |> Constraint.check retryCount |> Result.mapError Violation.renderRuns a constraint and returns the unchanged value after success.
Parameters
| Name | Type | Description |
|---|---|---|
| constraint' | Constraint<'value> | |
| value | 'value |
Returns
Result<'value, Violation>
Verification Examples
let requiredName : Constraint<string> = Constraint.present
"Alice" |> Constraint.guard requiredName |> Result.mapError Violation.renderReturns the constraint's inspectable description.
Parameters
| Name | Type | Description |
|---|---|---|
| constraint' | Constraint<'value> |
Returns
ConstraintDescription
Verification Examples
let requiredName : Constraint<string> = Constraint.present
(Constraint.inspect requiredName).Expression
Requires every constraint to hold, evaluating each in declaration order and accumulating failures. The
empty list is the satisfied identity.
Parameters
| Name | Type | Description |
|---|---|---|
| constraints | Constraint<'value> list |
Returns
Constraint<'value>
Verification Examples
let requiredName : Constraint<string> =
Constraint.all [ Constraint.present; Constraint.lengthBetween 2 40 ]
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
| Name | Type | Description |
|---|---|---|
| first | Constraint<'value> | |
| rest | Constraint<'value> list |
Returns
Constraint<'value>
Verification Examples
let ttl : Constraint<int> =
Constraint.any (Constraint.equalTo -1) [ Constraint.atLeast 1 ]
Negates a constraint. The result is opaque: it runs normally but cannot be exported or proved, and reports
the supplied prose.
Parameters
| Name | Type | Description |
|---|---|---|
| description | string | |
| constraint' | Constraint<'value> |
Returns
Constraint<'value>
Verification Examples
Constraint.notWith "must not be a reserved name" (Constraint.oneOf [ "admin"; "root" ])Runs an arbitrary predicate, reporting the supplied prose when it fails.
Parameters
| Name | Type | Description |
|---|---|---|
| description | string | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Verification Examples
let isValidIsbn (isbn: string) = isbn.Length = 13 in Constraint.custom "must be a valid ISBN" isValidIsbn
Runs an arbitrary predicate, reporting the supplied prose and the author's own catalogue key when it fails.
Parameters
| Name | Type | Description |
|---|---|---|
| key | string | |
| description | string | |
| 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
Runs an arbitrary predicate, reporting the supplied prose plus a catalogue key and named arguments a
translation can interpolate.
Parameters
| Name | Type | Description |
|---|---|---|
| key | string | |
| description | string | |
| arguments | Map<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 ])
isValidIsbnRuns an arbitrary callback that reports its own violation.
Parameters
| Name | Type | Description |
|---|---|---|
| description | string | |
| 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))Applies a constraint to a projection of a larger value.
Parameters
| Name | Type | Description |
|---|---|---|
| project | 'input -> 'value | |
| constraint' | Constraint<'value> |
Returns
Constraint<'input>
Verification Examples
Constraint.present |> Constraint.contramap (fun order -> order.Reference)Attaches documentary prose to a constraint.
Parameters
| Name | Type | Description |
|---|---|---|
| description | string | |
| constraint' | Constraint<'value> |
Returns
Constraint<'value>
Verification Examples
Constraint.between 0 10 |> Constraint.describe "Retries before the call is abandoned."Requires a value to be inhabited according to its shape.
Returns
Constraint<^value>
Verification Examples
let requiredName : Constraint<string> = Constraint.presentRequires a value to be uninhabited according to its shape; the exact complement of
present.Returns
Constraint<^value>
Verification Examples
let mustBeUnset : Constraint<string> = Constraint.blankLifts a constraint over an optional container: absence passes, presence runs the inner constraint.
Parameters
| Name | Type | Description |
|---|---|---|
| inner | Constraint<'value> |
Returns
Constraint<^container>
Verification Examples
let nickname : Constraint<string option> =
Constraint.optional (Constraint.lengthBetween 2 40)Requires text or a collection to have exactly the supplied size.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | int |
Returns
Constraint<^value>
Verification Examples
let code : Constraint<string> = Constraint.length 6Requires text or a collection to have at least the supplied size.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | int |
Returns
Constraint<^value>
Verification Examples
let tags : Constraint<string list> = Constraint.minLength 1Requires text or a collection to have at most the supplied size.
Parameters
| Name | Type | Description |
|---|---|---|
| maximum | int |
Returns
Constraint<^value>
Verification Examples
let summary : Constraint<string> = Constraint.maxLength 280Requires a text or collection size inside the supplied inclusive bounds.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | int | |
| maximum | int |
Returns
Constraint<^value>
Verification Examples
let name : Constraint<string> = Constraint.lengthBetween 2 40Requires a collection to hold exactly one item.
Returns
Constraint<^value>
Verification Examples
let primaryAddress : Constraint<Address list> = Constraint.singleRequires a collection to hold at least one item.
Returns
Constraint<^value>
Verification Examples
let tags : Constraint<string list> = Constraint.atLeastOneRequires a collection to hold no more than one item.
Returns
Constraint<^value>
Verification Examples
let overrides : Constraint<Rule list> = Constraint.atMostOneRequires a collection to hold two or more items.
Returns
Constraint<^value>
Verification Examples
let participants : Constraint<Party list> = Constraint.moreThanOneThe exact regular expression
Constraint.email runs.Returns
string
The exact regular expression
Constraint.numeric runs.Returns
string
The regular expression an exporter may publish for
Constraint.present on text.Returns
string
The regular expression an exporter may publish for
Constraint.trimmed.Returns
string
Requires text to match Reified's pragmatic email shape,
^[^@]+@[^@]+$.Returns
Constraint<string>
Verification Examples
let contact : Constraint<string> = Constraint.emailRequires text to have no leading or trailing whitespace.
Returns
Constraint<string>
Verification Examples
let slug : Constraint<string> = Constraint.trimmedRequires text to be one or more ASCII digits.
Returns
Constraint<string>
Verification Examples
let pin : Constraint<string> = Constraint.numericRequires text to be one or more letters or digits.
Returns
Constraint<string>
Verification Examples
let handle : Constraint<string> = Constraint.alphanumericRequires text to match the supplied .NET regular expression.
Parameters
| Name | Type | Description |
|---|---|---|
| expression | string |
Returns
Constraint<string>
Verification Examples
let reference : Constraint<string> = Constraint.pattern @"^[A-Z]{3}-\d{4}$"Builds a relation from an already-projected operand. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| operator | RelationOperator | |
| expected | ConstraintValue option | |
| actual | 'value -> ConstraintValue option | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Builds an inclusive range from already-projected bounds. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | ConstraintValue option | |
| maximum | ConstraintValue option | |
| actual | 'value -> ConstraintValue option | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Builds a membership rule from already-projected choices. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| choices | ConstraintValue option list | |
| actual | 'value -> ConstraintValue option | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Builds an exclusion rule from already-projected choices. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| choices | ConstraintValue option list | |
| actual | 'value -> ConstraintValue option | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Validates inclusive bounds. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| name | string | |
| minimum | 'a | |
| maximum | 'a |
Returns
unit
Requires equality with the supplied value, under F# structural equality.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | 'value |
Returns
Constraint<'value>
Verification Examples
let mustBeDraft : Constraint<Status> = Constraint.equalTo Status.DraftRequires inequality with the supplied value, under F# structural equality.
Parameters
| Name | Type | Description |
|---|---|---|
| unexpected | 'value |
Returns
Constraint<'value>
Verification Examples
let notReserved : Constraint<string> = Constraint.notEqualTo "admin"Requires a value strictly greater than the supplied bound.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | 'value |
Returns
Constraint<'value>
Verification Examples
let quantity : Constraint<int> = Constraint.greaterThan 0Requires a value strictly less than the supplied bound.
Parameters
| Name | Type | Description |
|---|---|---|
| maximum | 'value |
Returns
Constraint<'value>
Verification Examples
let discount : Constraint<decimal> = Constraint.lessThan 1.0MRequires a value greater than or equal to the supplied bound.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | 'value |
Returns
Constraint<'value>
Verification Examples
let age : Constraint<int> = Constraint.atLeast 13Requires a value less than or equal to the supplied bound.
Parameters
| Name | Type | Description |
|---|---|---|
| maximum | 'value |
Returns
Constraint<'value>
Verification Examples
let weight : Constraint<int> = Constraint.atMost 100Requires a value inside the supplied inclusive bounds.
Parameters
| Name | Type | Description |
|---|---|---|
| minimum | 'value | |
| maximum | 'value |
Returns
Constraint<'value>
Verification Examples
let retryCount : Constraint<int> = Constraint.between 0 10Requires a value strictly greater than zero.
Returns
Constraint<^value>
Verification Examples
let quantity : Constraint<int> = Constraint.positiveRequires a value of zero or greater.
Returns
Constraint<^value>
Verification Examples
let balance : Constraint<decimal> = Constraint.nonNegativeRequires a value strictly less than zero.
Returns
Constraint<^value>
Verification Examples
let adjustment : Constraint<int> = Constraint.negativeRequires a value of zero or less.
Returns
Constraint<^value>
Verification Examples
let drawdown : Constraint<int> = Constraint.nonPositiveRequires the value to equal one of the supplied choices.
Parameters
| Name | Type | Description |
|---|---|---|
| choices | 'value seq |
Returns
Constraint<'value>
Verification Examples
let currency : Constraint<string> = Constraint.oneOf [ "AUD"; "NZD" ]Requires the value to equal none of the supplied choices.
Parameters
| Name | Type | Description |
|---|---|---|
| choices | 'value seq |
Returns
Constraint<'value>
Verification Examples
let handle : Constraint<string> = Constraint.noneOf [ "admin"; "root" ]Builds a containment rule from an already-projected item. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | ConstraintValue option | |
| values | 'a -> bool |
Returns
Constraint<'a>
Builds an exclusion rule from an already-projected item. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | ConstraintValue option | |
| values | 'a -> bool |
Returns
Constraint<'a>
Builds a uniqueness rule with a caller-supplied item projection. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| item | 'value -> ConstraintValue option | |
| duplicate | 'a -> 'value option |
Returns
Constraint<'a>
The containment predicate. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | 'value | |
| values | 'a |
Returns
bool
The exclusion predicate. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | 'value | |
| values | 'a |
Returns
bool
The first-duplicate projection. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| values | 'a |
Returns
'value option
Requires a collection to contain the supplied item.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | 'value |
Returns
Constraint<^container>
Verification Examples
let mustIncludeAdmin : Constraint<string list> = Constraint.contains "admin"Requires a collection not to contain the supplied item.
Parameters
| Name | Type | Description |
|---|---|---|
| expected | 'value |
Returns
Constraint<^container>
Verification Examples
let tags : Constraint<string list> = Constraint.notContains "internal"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.distinctBuilds a divisibility rule from an already-projected divisor. Not part of the supported surface.
Parameters
| Name | Type | Description |
|---|---|---|
| divisor | ConstraintValue option | |
| actual | 'value -> ConstraintValue option | |
| predicate | 'value -> bool |
Returns
Constraint<'value>
Requires an exact multiple of the supplied divisor, under the value type's own arithmetic.
Parameters
| Name | Type | Description |
|---|---|---|
| divisor | ^value |
Returns
Constraint<^value>
Verification Examples
let batchSize : Constraint<int> = Constraint.multipleOf 10Requires a double to be neither infinite nor
NaN.Returns
Constraint<float>
Verification Examples
let ratio : Constraint<float> = Constraint.finite