zmodel_to_dart_runtime

Runtime contracts and helpers for Dart code generated from ZModel schemas.

This package is intended to be used as a normal runtime dependency by apps that compile generated DTOs, mutations, enums, and RPC clients. Use it together with zmodel_to_dart_builder when generating code from .zmodel files. The original zmodel_to_dart pub package is left as the legacy 0.x package.

For implementation details, see the repository architecture guide.

Usage

Add the runtime package to dependencies:

dependencies:
  zmodel_to_dart_runtime: ^1.0.3

dev_dependencies:
  zmodel_to_dart_builder: ^1.0.3
  build_runner: ^2.7.0

Generated files import the runtime API:

import 'package:zmodel_to_dart_runtime/zmodel_to_dart_runtime.dart';

Runtime Surface

  • ZModel, the base contract for generated models
  • ZModelField and typed field implementations exposed through lowercase schema field keys
  • ZModelEnum, used by generated Dart enums with schema values
  • scalar, enum, bytes, model, and list coercion helpers
  • ZValidationError, ZFieldValidator, ZModelValidator, and configurable validation messages
  • ZRpcTransport, ZHttpMethod, ZHttpResponse, ZRpcClient, ZModelRpcApi, and generated model payload contracts
  • SuperJson utilities

ZHttpResponse keeps the transport response data used by generated clients: status code, status message, headers, and decoded data.

ZModelRpcApi exposes model-scoped RPC helpers for findMany, findUnique, findFirst, create, createMany, update, updateMany, upsert, delete, deleteMany, and count. Generated payload classes implement runtime contracts such as ZModelWhere, ZModelWhereUnique, ZModelOrderBy, ZModelDistinct, ZModelCreate, ZModelCreateMany, ZModelUpdate, ZModelSelect, ZModelOmit, and ZModelInclude.

See example/main.dart for a complete generated-code shape using User, Post, and Role.

Field Metadata

Generated models expose typed ZModelField instances directly on the model. The field value is available through .value, and .isSet reports whether the JSON payload explicitly included the field:

final name = user.name.value;
final hasName = user.name.isSet;

Models also expose fields by lowercase schema/JSON name:

final field = user.fields['parameter_id'];

Enum fields receive the generated Dart enum values:

final role = ZModelEnumField<Role>('role', Role.values);
role.fromJson('admin');

Validation

Generated models expose field and model validators:

final nameError = User.validators.name.required()(name);

final result = User.validators.validateMap({
  'id': 'user_1',
  'name': name,
  'role': 'admin',
});

Validators return structured errors instead of hard-coded user-facing text:

final error = result.firstError;
print(error?.code);
print(error?.fieldMessageKey);

Configure the default message resolver globally:

ZValidationMessages.resolver = (error) {
  return switch (error.code) {
    ZValidationErrorCode.required => 'Campo obrigatório',
    ZValidationErrorCode.invalidType => 'Valor inválido',
    ZValidationErrorCode.invalidEnum => 'Opção inválida',
    ZValidationErrorCode.minLength => 'Valor muito curto',
    ZValidationErrorCode.maxLength =>
      "Use no máximo ${error.metadata['maxLength']} caracteres",
    ZValidationErrorCode.email => 'E-mail inválido',
    _ => 'Valor inválido',
  };
};

Form-specific overrides do not change the generated schema validator:

final formValidator = User.validators.model.withFields({
  'name': User.validators.name.required(),
});

final formResult = formValidator.validateMap(formData);

License

MIT

Libraries

zmodel_to_dart_runtime
Runtime contracts and helpers for generated ZModel Dart code.