From 1e8beecff81ab4a9459238ccd549e09b1f6d9d67 Mon Sep 17 00:00:00 2001 From: Leo Farias Date: Wed, 15 Jul 2026 06:53:13 -0400 Subject: [PATCH] docs: align contracts and fixture dependencies --- docs.json | 2 +- docs/api-reference/index.mdx | 35 ++++++++++++++------ docs/core-concepts/schemas.mdx | 5 ++- docs/core-concepts/validation.mdx | 4 ++- docs/getting-started/quickstart-tutorial.mdx | 5 ++- llms.txt | 7 ++-- packages/ack_firebase_ai/README.md | 2 +- packages/ack_firebase_ai/pubspec.yaml | 9 +++-- packages/ack_generator/README.md | 3 ++ 9 files changed, 52 insertions(+), 20 deletions(-) diff --git a/docs.json b/docs.json index 5a23af11..5755aea2 100644 --- a/docs.json +++ b/docs.json @@ -75,7 +75,7 @@ ], "variables": { "versions": { - "default": "1.0.0", + "default": "1.1.0", "isPrerelease": false } }, diff --git a/docs/api-reference/index.mdx b/docs/api-reference/index.mdx index 8d07e818..9bd611d9 100644 --- a/docs/api-reference/index.mdx +++ b/docs/api-reference/index.mdx @@ -16,8 +16,9 @@ Entry point for creating schemas. See [Schema Types](../core-concepts/schemas.md - `Ack.list(AckSchema itemSchema)`: Creates a `ListSchema` for validating arrays. Nullable item schemas are not supported; make the list itself nullable instead. - `Ack.object(Map properties)`: Creates an `ObjectSchema` for validating objects. - `Ack.enumValues(List values)`: Creates an `EnumSchema` for Dart enum - types. Accepts enum instances, string names, or indices. **Preferred over - `enumString` when a Dart enum exists.** + types. Parses enum `.name` strings into typed enum values. Pass typed enum + values to `encode` or `safeEncode` for the reverse direction. **Preferred + over `enumString` when a Dart enum exists.** - `Ack.enumCodec(List values)`: Like `enumValues`, but returns a `CodecSchema` instead of an `EnumSchema`. Use this when downstream code expects every value-shape to be a `CodecSchema` (e.g. a @@ -33,9 +34,11 @@ Entry point for creating schemas. See [Schema Types](../core-concepts/schemas.md - `Ack.codec(...)` / `Ack.date()` / `Ack.datetime()` / `Ack.uri()` / `Ack.duration()` / `Ack.enumCodec(...)`: Create codecs. See [Codecs](../core-concepts/codecs.mdx). -- `Ack.lazy(String name, AckSchema Function() builder)`: Creates a memoized - deferred schema reference for recursive schema graphs. JSON Schema export - renders Draft-7 `definitions` / `$ref` entries using `name`. +- `Ack.lazy(String name, AckSchema Function() builder, {int maxDepth = 100})`: + Creates a memoized deferred schema reference for recursive schema graphs. + `maxDepth` must be at least `1` and limits parsing, runtime validation, and + encoding. JSON Schema export renders Draft-7 `definitions` / `$ref` entries + using `name` but warns that the runtime-only depth limit was omitted. - `Ack.discriminated(...)`: Creates a discriminated union schema. Branches may be plain `ObjectSchema` or transformed schemas whose base is an `ObjectSchema`. The union owns the discriminator: branches normally @@ -49,7 +52,10 @@ Base class for all schema types. ### Primary Validation Methods -- `SchemaResult safeParse(Object? data, {String? debugName})`: Validates `data` and returns a `SchemaResult`. Never throws; use `.getOrNull()` to get the value without risk of an exception. +- `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. - `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`. - `TOut parseAs(Object? data, TOut Function(Runtime?) map, {String? debugName})`: Throwing variant of `safeParseAs`. @@ -101,7 +107,7 @@ Schema for validating strings. See [String Validation](../core-concepts/validati - `email()`: Must be valid email format - `url()`: Must be valid URL format (alias for `uri()`) -- `uri()`: Must be valid URI according to RFC 3986 +- `uri()`: Must be a valid absolute URI with a scheme and host - `uuid()`: Must be valid UUID format - `ip({int? version})`: Must be valid IP address (version 4 or 6) - `ipv4()`: Must be valid IPv4 address @@ -189,9 +195,11 @@ Represents a validation failure. See [Error handling](../core-concepts/error-han - `SchemaContext context`: Context about where the error occurred. **Subclasses:** +- `TypeMismatchError`: The input has the wrong Dart runtime type. - `SchemaConstraintsError`: One or more constraint violations. - `SchemaNestedError`: Validation failures in nested objects or arrays. - `SchemaValidationError`: Custom refinement failures. +- `SchemaTransformError`: Decode/transform callback failures. - `SchemaEncodeError`: Encode-path failures (non-nullable null, one-way transform, encoder threw, etc.). ## `Constraint` @@ -235,10 +243,15 @@ Schema for polymorphic validation based on a string discriminator property. Schema reference for recursive object graphs. -- Created using `Ack.lazy(name, builder)`. +- Created using `Ack.lazy(name, builder)`. `maxDepth` + defaults to `100` and must be at least `1`; pass it explicitly only to + override the default. - The builder is resolved once and memoized. +- Exceeding `maxDepth` returns a validation failure during parsing, runtime + validation, or encoding. - `toJsonSchema()` and `toSchemaModel()` export Draft-7 `definitions` / `$ref` - entries using the lazy `name`. + entries using the lazy `name`. The runtime-only depth limit cannot be + represented by `$ref`, so exported schema models warn that it was omitted. - Bare or wrapped lazy schemas cannot be used as discriminated-union branches because the branch discriminator must be analyzable at construction time. @@ -290,7 +303,9 @@ print(user.email); // Type-safe String access ### `EnumSchema` -Schema for validating enum values. Created using `Ack.enumValues(List values)` where `T extends Enum`. +Schema for mapping enum `.name` strings at the boundary to typed enum values at +runtime. Created using `Ack.enumValues(List values)` where `T extends Enum`; +`encode` and `safeEncode` map typed enum values back to their names. ### `AnyOfSchema` diff --git a/docs/core-concepts/schemas.mdx b/docs/core-concepts/schemas.mdx index b15e092e..04523bb5 100644 --- a/docs/core-concepts/schemas.mdx +++ b/docs/core-concepts/schemas.mdx @@ -203,7 +203,10 @@ categorySchema = Ack.object({ The lazy builder is resolved once and memoized. JSON Schema export renders the reference through Draft-7 `definitions` / `$ref`, so recursive children are -referenced rather than inlined forever. +referenced rather than inlined forever. `maxDepth` defaults to `100`, must be at +least `1`, and returns a validation failure when parsing, runtime validation, or +encoding exceeds the limit. Because the limit is runtime-only and cannot be +represented by `$ref`, exported schema models warn that it was omitted. ### Any diff --git a/docs/core-concepts/validation.mdx b/docs/core-concepts/validation.mdx index 5d81f584..dba5e873 100644 --- a/docs/core-concepts/validation.mdx +++ b/docs/core-concepts/validation.mdx @@ -97,7 +97,9 @@ Ack.string().time() ``` ### `uri()` -Requires a valid URI per RFC 3986. +Requires a valid absolute URI with a scheme and host. This is the network-URI +subset Ack accepts, rather than every relative or non-host URI permitted by RFC +3986. ```dart Ack.string().uri() ``` diff --git a/docs/getting-started/quickstart-tutorial.mdx b/docs/getting-started/quickstart-tutorial.mdx index 2e3f1399..40f2dde8 100644 --- a/docs/getting-started/quickstart-tutorial.mdx +++ b/docs/getting-started/quickstart-tutorial.mdx @@ -25,7 +25,10 @@ See [Schema Types](../core-concepts/schemas.mdx) and [Validation Rules](../core- ## 2. Validate data -Call `safeParse()` with the data you received — for example `jsonDecode(response.body)`. It returns a `SchemaResult` and never throws. +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. ```dart final result = userSchema.safeParse({'name': 'Alice', 'age': 30}); diff --git a/llms.txt b/llms.txt index 19392a4b..d3eaf892 100644 --- a/llms.txt +++ b/llms.txt @@ -173,8 +173,9 @@ AckType generation is intentionally strict: - `schema.parse(data)` throws on invalid input - `schema.safeParse(data)` returns `SchemaResult` -- `safeParse` does not throw; exceptions from validation/refinement callbacks - are returned as contextual validation failures +- `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 - `SchemaResult.getOrThrow()` returns the validated value or throws `AckException` - `.optional()` allows a field to be omitted - `.nullable()` allows a present field to hold `null` @@ -183,6 +184,8 @@ AckType generation is intentionally strict: - `schema.toJsonSchema()` renders `schema.toSchemaModel().toJsonSchema()` - adapter packages should render from `AckSchemaModel`, not by traversing `AckSchema` subclasses - `Ack.list(...)` does not support nullable item schemas; make the list itself nullable when needed +- `Ack.lazy(...)` defaults `maxDepth` to `100` for recursive parsing, runtime + validation, and encoding; the runtime-only limit is omitted from exported schemas with a warning - `Ack.object`, `Ack.anyOf`, and enum factories snapshot their input collections; unions and enum value lists must be non-empty, and enum values must be unique - lengths and item counts must be non-negative; numeric bounds must be finite; diff --git a/packages/ack_firebase_ai/README.md b/packages/ack_firebase_ai/README.md index 058f0b55..0876429a 100644 --- a/packages/ack_firebase_ai/README.md +++ b/packages/ack_firebase_ai/README.md @@ -25,7 +25,7 @@ Always validate model output with the same ACK schema after generation. Firebase dependencies: ack: ^1.0.0 ack_firebase_ai: ^1.0.0 - firebase_ai: ^3.12.1 + firebase_ai: ^3.12.2 ``` This package targets Firebase AI's map-based `responseJsonSchema` API for models that support JSON Schema structured output. diff --git a/packages/ack_firebase_ai/pubspec.yaml b/packages/ack_firebase_ai/pubspec.yaml index d55c723d..e83c3d8a 100644 --- a/packages/ack_firebase_ai/pubspec.yaml +++ b/packages/ack_firebase_ai/pubspec.yaml @@ -15,9 +15,12 @@ dependencies: sdk: flutter dev_dependencies: - firebase_core: ^4.9.0 - firebase_core_platform_interface: ^7.0.1 - firebase_ai: '>=3.12.1 <3.13.0' + # Keep the generated Firebase fixture and its compile-time SDK matrix exact. + firebase_ai: 3.12.2 + firebase_app_check: 0.4.5 + firebase_auth: 6.5.4 + firebase_core: 4.11.0 + firebase_core_platform_interface: 7.1.0 flutter_test: sdk: flutter lints: ^5.0.0 diff --git a/packages/ack_generator/README.md b/packages/ack_generator/README.md index 2aaaae77..c42e0083 100644 --- a/packages/ack_generator/README.md +++ b/packages/ack_generator/README.md @@ -79,6 +79,9 @@ validate through the union's effective branch. - Inline anonymous object branches are rejected for typed generation. Extract them to a named top-level schema first. - Nullable top-level schemas do not emit extension types. +- Nullable list elements are rejected: `Ack.list(item.nullable())` is not + supported. Make the list nullable with `Ack.list(item).nullable()` when the + list itself may be `null`. - `@AckType()` requires static schema resolution for nested object references. ## Build commands