zmodel_to_dart_runtime 1.1.1

Runtime contracts and helpers for Dart code generated from ZModel schema files

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.1.0

dev_dependencies:
  zmodel_to_dart_builder: ^1.1.0
  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
• ZModelMetadata, ZModelFieldMetadata, and metadata entry objects for dynamic payload construction
• 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'];

Generated models also expose static schema metadata:

final userMetadata = User.metadata;
final emailField = User.metadata.email;

Field metadata can build typed entries for dynamic payloads without using raw field strings:

final select = UserSelect().setEntries([
  User.metadata.id.select(),
  User.metadata.email.select(),
]);

final where = UserWhere().setEntries([
  User.metadata.email.contains('example.com'),
]);

final orderBy = UserOrderBy([
  User.metadata.createdAt.desc(),
  User.metadata.id.asc(),
]);

Nested field paths can be composed from relation metadata:

final authorEmail = Post.metadata.author.field(User.metadata.email);

final where = PostWhere().setEntry(
  authorEmail.contains('example.com'),
);

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