dust_dart

Dart annotations and runtime APIs for code generated by Dust.

Use this package for data classes, JSON serialization, validation, typed HTTP clients, functional result types, and Database annotations. Flutter-specific features live in dust_flutter.

Installation

Add the package to a Dart or Flutter project:

dart pub add dust_dart

Install the Dust CLI by following the main installation guide. If the CLI and package versions differ, check the compatibility guide.

Quick Start

Declare the generated part and select the derives your model needs:

import 'package:dust_dart/serde.dart';

part 'user.g.dart';

@Derive([Eq(), CopyWith(), Serialize(), Deserialize()])
class User with _$User {
  const User({required this.id, required this.name});

  factory User.fromJson(Map<String, Object?> json) => _$UserFromJson(json);

  final String id;
  final String name;
}

Generate and verify the output:

dust build
dust check

The model now has typed copyWith, equality, serialize, toJson, and fromJson support:

final user = User.fromJson({'id': '1', 'name': 'Aye'});
final renamed = user.copyWith(name: 'Moe');
final json = renamed.serialize();
final dartJson = renamed.toJson(); // Dart ecosystem mirror.

Generated JSON support also includes source-only Serializer<DartT, JsonT> and Deserializer<DartT, JsonT> objects for call sites that want reusable conversion objects instead of instance methods. serde.dart provides toJson and fromJson extension mirrors for Dart ecosystem naming.

Libraries

Prefer focused imports when a file uses one feature area:

Import	Provides
package:dust_dart/derive.dart	Data-class and validation annotations.
package:dust_dart/serde.dart	JSON annotations, codecs, and derive exports.
package:dust_dart/http.dart	Typed HTTP client annotations and runtime types.
package:dust_dart/fp.dart	Option, Result, Unit, and their variants.
package:dust_dart/db.dart	Beta Database annotations and runtime contracts.
package:dust_dart/dust_dart.dart	Convenience export for every Dart-only API.

Functional Types

These are Dust's own types, not a re-export of fpdart or dartz. Generated code returns them, so a runtime built on a functional package would put that package in the dependency graph of every project running dust build.

Option<T> distinguishes absence from presence, including a present null. Result<T, E> represents typed success or failure:

import 'package:dust_dart/fp.dart';

Result<int, String> parseCount(String text) {
  final value = int.tryParse(text);
  return value == null ? const Err('invalid count') : Ok(value);
}

final label = parseCount('42').match(
  ok: (value) => 'count=$value',
  err: (error) => error,
);

Option follows Rust's names:

Kind	Methods
Build and read	Option.fromNullable, isSome, isNone, toNullable, toIterable
Query	contains, isSomeAnd, isNoneOr
Extract	unwrap, expect, unwrapOr, unwrapOrElse, match
Transform	map, mapOr, mapOrElse, andThen, inspect, filter
Choose	and, or, orElse, xor
Combine	zip, zipWith, unzip, flatten
With Result	okOr, okOrElse, transpose

Some<T?>(null) is a present value and stays one; only toNullable turns it back into a bare null. unwrap and expect throw StateError on None.

Result<int, String> readAge(Map<String, Object?> json) {
  return Option<int>.fromNullable(json['age'] as int?)
      .filter((value) => value >= 0)
      .okOr('age is missing or negative');
}

Documentation

• Data classes
• JSON serialization
• Validation
• HTTP clients
• Database
• Product showcase

Data classes, JSON, validation, and HTTP client APIs are stable. Database APIs are beta and may change while that feature is hardened.

Report problems through the Dust issue tracker. Contributions follow the repository's contributor guide.

Licensed under the MIT License.

Libraries

core

Stable compatibility export for Dart-only Dust functional primitives.

db

Beta SQLx-style DB annotations and runtime for Dust.

derive

Derive annotations for Dust model generation.

dust_dart

Unified Dart runtime and annotations for Dust code generation.

fp

Stable functional primitives for Dust runtimes and generated code.

http

HTTP client annotations and runtime exports for Dust.

serde

SerDe annotations for Dust JSON generation.