You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Version 1.1.0 introduces a behavioral change to `Value.Parse(...)` and `Validator.Parse(...)` where automatic corrective parsing is now disabled by default. This change addresses performance overhead when handling invalid data and prepares the `Value.*` API for future revisions.
6
+
7
+
This update introduces a validation semantics change and is published under a minor semver version.
8
+
9
+
## Corrective Parse
10
+
11
+
In 1.0, a feature referred to as “Corrective Parse” was trialed. This feature meant that for any invalid value passed to Parse, TypeBox would attempt to Convert, Default, and Clean the value, then re-Check it before throwing an assertion. The feature was introduced in 1.0 in an effort to establish a de facto parsing pipeline for TypeBox, but it has since been observed that it incurs significant performance overhead for large invalid values. Additionally, the correction behavior has generally proven surprising to users, and is therefore better expressed as an opt-in feature.
12
+
13
+
The following shows the changes from 1.0 to 1.1
14
+
15
+
```typescript
16
+
// 1.0
17
+
const A =Value.Parse(Type.Number(), '123') // A = 123
18
+
19
+
// 1.1
20
+
const A =Value.Parse(Type.Number(), '123') // throw! - Expected Number
21
+
```
22
+
23
+
Corrective parsing can be re-enabled by using the `{ correctiveParse: true }` configuration.
24
+
25
+
```typescript
26
+
import { Settings } from'typebox/system'
27
+
28
+
// 1.1
29
+
Settings.Set({ correctiveParse: true })
30
+
31
+
const A =Value.Parse(Type.Number(), '123') // A = 123
The Parse function attempts to parse a value and throws an error if the value is invalid. This function is similar to Decode, but it does not execute Decode callbacks. Parse is considered a faster version of Decode, as operations that transform values are skipped when the value already matches the expected type.
4
-
5
-
> The Parse function first checks a value against the provided type and returns immediately if it matches. If the value does not match, it is processed through a sequence of Clone, Clean, Convert, and Default operations, and then re-checked. If the value remains invalid, a ParseError error is thrown.
3
+
The Parse function validates and returns a value that conforms to a given type. If the value does not satisfy the type, a parse error is thrown.
6
4
7
5
## Example
8
6
@@ -11,5 +9,31 @@ Example usage is shown below.
11
9
```typescript
12
10
const R =Value.Parse(Type.String(), 'hello') // const R: string = "hello"
13
11
14
-
const E =Value.Parse(Type.String(), [{ x: 1 }]) // throws ParseError
12
+
const E =Value.Parse(Type.String(), 12345) // throws ParseError
13
+
```
14
+
15
+
## Corrective Parse
16
+
17
+
TypeBox provides an optional corrective parsing mode that attempts to repair invalid values before failing. When enabled, the parser runs a pipeline consisting of Convert, Default, and Clean, then re-asserts the value after processing. This feature can be useful when parsing environment variables into target types.
18
+
19
+
> ⚠️ This feature can impact performance. It is not recommended for use in high throughput applications.
20
+
21
+
This feature can be enabled as follows:
22
+
23
+
```typescript
24
+
import { Settings } from'typebox/system'
25
+
26
+
// Corrective Parse: Enable
27
+
28
+
Settings.Set({ correctiveParse: true })
29
+
30
+
// Corrective Parse: Convert Value into the target type if reasonable conversion is possible.
31
+
32
+
const R =Value.Parse(Type.String(), 'hello') // const R: string = "hello"
33
+
34
+
const S =Value.Parse(Type.String(), 12345) // const S: string = "12345"
<p>The Parse function attempts to parse a value and throws an error if the value is invalid. This function is similar to Decode, but it does not execute Decode callbacks. Parse is considered a faster version of Decode, as operations that transform values are skipped when the value already matches the expected type.</p>
3
-
<blockquote>
4
-
<p>The Parse function first checks a value against the provided type and returns immediately if it matches. If the value does not match, it is processed through a sequence of Clone, Clean, Convert, and Default operations, and then re-checked. If the value remains invalid, a ParseError error is thrown.</p>
5
-
</blockquote>
2
+
<p>The Parse function validates and returns a value that conforms to a given type. If the value does not satisfy the type, a parse error is thrown.</p>
const E = Value.Parse(Type.String(), 12345) // throws ParseError
8
+
</code></pre>
9
+
<h2>Corrective Parse</h2>
10
+
<p>TypeBox provides an optional corrective parsing mode that attempts to repair invalid values before failing. When enabled, the parser runs a pipeline consisting of Convert, Default, and Clean, then re-asserts the value after processing. This feature can be useful when parsing environment variables into target types.</p>
11
+
<blockquote>
12
+
<p>⚠️ This feature can impact performance. It is not recommended for use in high throughput applications.</p>
13
+
</blockquote>
14
+
<p>This feature can be enabled as follows:</p>
15
+
<pre><codeclass="language-typescript">import { Settings } from 'typebox/system'
16
+
17
+
// Corrective Parse: Enable
18
+
19
+
Settings.Set({ correctiveParse: true })
20
+
21
+
// Corrective Parse: Convert Value into the target type if reasonable conversion is possible.
0 commit comments