From 0c21775aa4bc74e6ee1b2953d29ee6a0dcbcfa16 Mon Sep 17 00:00:00 2001 From: Leo Farias Date: Wed, 15 Jul 2026 07:25:40 -0400 Subject: [PATCH] docs: clarify safeParse callback errors --- docs/api-reference/index.mdx | 8 +++++--- docs/getting-started/quickstart-tutorial.mdx | 6 ++++-- llms.txt | 7 +++++-- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/api-reference/index.mdx b/docs/api-reference/index.mdx index 9bd611d9..f20401d4 100644 --- a/docs/api-reference/index.mdx +++ b/docs/api-reference/index.mdx @@ -54,10 +54,12 @@ Base class for all schema types. - `SchemaResult safeParse(Object? data, {String? debugName})`: Validates `data` and returns a `SchemaResult`. Invalid input and recoverable `Exception` - values thrown by validation callbacks become failures. Programmer/runtime - `Error` values are rethrown with their original stack trace. + values thrown by constraint/refinement callbacks become failures. `Error` + values from those callbacks are rethrown with their original stack trace. + Codec/transform decoder failures, including `Error` values, become + `SchemaTransformError` failures. - `Runtime? parse(Object? data, {String? debugName})`: Validates `data` and returns the value; throws `AckException` on failure. -- `SchemaResult safeParseAs(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Parses and maps the validated value to `TOut`. +- `SchemaResult safeParseAs(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Parses and maps the validated value to `TOut`. Mapper failures, including `Error` values, become `SchemaTransformError` failures. - `TOut parseAs(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Throwing variant of `safeParseAs`. - `SchemaResult safeEncode(Runtime? value, {String? debugName})`: Encodes a runtime value to the boundary representation. - `Boundary? encode(Runtime? value, {String? debugName})`: Throwing variant of `safeEncode`. diff --git a/docs/getting-started/quickstart-tutorial.mdx b/docs/getting-started/quickstart-tutorial.mdx index 40f2dde8..44a38f75 100644 --- a/docs/getting-started/quickstart-tutorial.mdx +++ b/docs/getting-started/quickstart-tutorial.mdx @@ -27,8 +27,10 @@ See [Schema Types](../core-concepts/schemas.mdx) and [Validation Rules](../core- Call `safeParse()` with the data you received — for example `jsonDecode(response.body)`. It returns a `SchemaResult` for invalid input and -for recoverable `Exception` values thrown by validation callbacks. -Programmer/runtime `Error` values are rethrown with their original stack trace. +for recoverable `Exception` values thrown by constraint/refinement callbacks. +`Error` values from those callbacks are rethrown with their original stack +trace. Codec/transform decoders and `safeParseAs` mappers instead turn thrown +values, including `Error` values, into `SchemaTransformError` failures. ```dart final result = userSchema.safeParse({'name': 'Alice', 'age': 30}); diff --git a/llms.txt b/llms.txt index d3eaf892..7c4e756c 100644 --- a/llms.txt +++ b/llms.txt @@ -174,8 +174,11 @@ AckType generation is intentionally strict: - `schema.parse(data)` throws on invalid input - `schema.safeParse(data)` returns `SchemaResult` - `safeParse` turns invalid input and recoverable `Exception` values from - validation/refinement callbacks into contextual failures -- programmer/runtime `Error` values are rethrown with their original stack trace + constraint/refinement callbacks into contextual failures +- `Error` values from constraint/refinement callbacks are rethrown with their + original stack trace +- codec/transform decoders and `safeParseAs` mappers turn thrown values, + including `Error` values, into `SchemaTransformError` failures - `SchemaResult.getOrThrow()` returns the validated value or throws `AckException` - `.optional()` allows a field to be omitted - `.nullable()` allows a present field to hold `null`