avesbox/acanthis

README

Acanthis

Composable runtime validation for Dart and Flutter. Define a schema, parse untrusted input, and get typed values or structured issues.

import 'package:acanthis/acanthis.dart';

void main() {
  final account = object({
    'name': string().trim().min(2),
    'email': string().email(),
    'age': integer().gte(18),
  });

  final result = account.tryParse({
    'name': ' Ada ',
    'email': 'ada@example.com',
    'age': 28,
  });

  if (result.isValid) {
    print(result.value['name']); // Ada
  } else {
    print(result.issues.formatFields());
  }
}

These docs describe the V2 code in this repository. Dart 3.13+ is required; Flutter projects need a compatible Dart SDK. Check the API version when using a published release.

Install

dart pub add acanthis
# Flutter projects:
flutter pub add acanthis

Parse, inspect, or check

API	Result
`schema.parse(input)`	Parsed output; throws `ValidationError` on failure
`schema.tryParse(input)`	`AcanthisValid<T>` or `AcanthisInvalid<T>` with issues
`schema.validate(input)`	Boolean, stopping at the first failure

Async schemas use the corresponding parseAsync, tryParseAsync, and validateAsync methods. Invalid outcomes may have typed recovery; it still fails validation. Read .value on success, or check AcanthisInvalid.hasValue before inspecting recovery.

Compose schemas

final name = string().min(2);
final names = name.list();
final nullableName = name.nullable();
final scores = record(string(), integer().gte(0));
final age = string().pipe(integer().gte(18), transform: int.parse);
final patch = object({'name': name}).patch();

Native fluent methods return new schemas. Object fields are required by default; unknown keys are stripped. Nullability permits null, while .optionals([...]) permits omission. Defaults replace missing/null input and are validated. .patch() preserves omitted fields, including those with defaults.

Parsed maps and lists can share input identity when unchanged. Copy containers if you need independent mutable data.

Explore the API

Quick start — define, parse, and handle issues.
Schema reference — primitives, objects, records, collections, instances, and composition.
Cross-field rules — parsed prerequisites, typed context, and cancellation.
Live validation — incremental edits, debouncing, revisions, and issue deltas.
Localization — presentation-time messages, English/Italian catalogs, and application overrides.
Metadata and registries — descriptions and typed schema lookup.
JSON Schema and OpenAPI — strict export and compiled import of supported JSON contracts.
Mock generation — bounded, reproducible samples and custom input generators.
Migrating to V2 — return types and compatibility changes.

Export and mocking have explicit supported subsets. Unsupported behavior fails with an explanation instead of silently weakening a contract or returning invalid data.

The website sources are in .website/. V2 reference notes describe detailed implementation contracts. Examples contain runnable Dart programs.

Work on the project

From the repository root:

dart pub get
dart analyze . --fatal-infos
dart test --reporter failures-only

Build the documentation from .website/:

npm ci
npm run docs:build

The contract guide documents the independent JSON/OpenAPI export audit. Benchmarks compare implementations; archived V1 sources live under v1/ for those comparisons.

Released changes are recorded in CHANGELOG.md. This project uses the MIT license.