Tooark.ValueObjects 4.7.0

Tooark.ValueObjects

Library of value objects that validate themselves on construction, for .NET projects.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📑 Contents

• Overview
• Installation
• Configuration
• Components
• Usage Examples
• Dependencies
• Contributing
• Help & Security
• Support
• License

📖 Overview

The Tooark.ValueObjects package provides:

• 33 value objects that validate themselves on construction, without throwing;
• translated notifications instead of exceptions, inherited from Notification;
• implicit conversion in both directions, so the type behaves like the value it represents;
• Brazilian documents with check digit verification: CPF, CNPJ, RG and CNH.

How it works. A value object never throws for invalid data: it is born with notifications. Whoever receives it checks IsValid before using the value.

var cpf = new Cpf("111.111.111-11");

cpf.IsValid       // false
cpf.Number        // "" — an invalid object carries no value
cpf.Notifications // the messages of what failed

An invalid object never returns null: it returns the empty value of its own type — an empty string in the 29 text objects, Guid.Empty in the four audit ones. That also holds for ToString(), so interpolation, concatenation and serialization are safe without a prior check.

🔧 Installation

dotnet add package Tooark.ValueObjects

⚙️ Configuration

Value objects require no registration at all. They validate on their own and, when something fails, keep the message key — Field.Invalid;Email, for instance. The layer that builds the response translates the key, not the value object.

The registration below only forwards to AddTooarkExtensions(), which makes the IStringLocalizer and the language files available to the application:

using Tooark.ValueObjects.Injections;

builder.Services.AddTooarkValueObjects();

📦 Components

Documents

Validate format and check digit.

Document is the generic form: without a type it assumes EDocumentType.None, which accepts any alphanumeric text — new Document("111") is valid, new Document("111", EDocumentType.CPF) is not. A rejected document has an empty Number and Type equal to None.

Text

Normalized returns the value without accents, without spaces and in uppercase — useful for searching and sorting. LanguageCode normalizes to the xx-XX format (e.g. pt-BR) and exposes the LanguageCode.Length constant (5) for external use, such as sizing columns.

Addresses and protocols

Note that LinkVideo and FileStorage expose Link, not Value. A FileStorage built without a name uses the link itself as Name. Email also has the constants Email.MinLength (6) and Email.MaxLength (255).

Email keeps the value in lowercase. The required format is stricter than RFC 5322: the local part and the domain need at least two characters, + is not accepted and leading/trailing spaces reject the value instead of being trimmed.

Auditing

Reject Guid.Empty. An invalid object has Value equal to Guid.Empty.

Password

Password does not leak the value. ToString() returns the mask, and there is no implicit conversion to text — the value only comes out through Value, explicitly:

var password = new Password("Password@123");

password.ToString()      // "********"
$"{password}"            // "********"
logger.LogInformation("{Password}", password);   // logs the mask
password.Value           // "Password@123" — the only path, and it is obvious when reading

The criteria apply exactly as given: disabling all of them means requiring only the length, which is a legitimate passphrase policy. The rule is the same applied by the PasswordValidationAttribute of Tooark.Attributes, because both use the PasswordPattern of Tooark.Validations.

Delimited string

Collections come in and go out as copies: changing the given array, or the returned one, does not change the object.

Implicit conversions

Every object converts in both directions with the type it represents — DelimitedString converts with three: string, string[] and List<string>:

Cpf cpf = "529.982.247-25";   // string -> value object
string number = cpf;          // value object -> string

The outbound conversion requires an instance: converting a null reference throws InternalServerErrorException with Invalid.Parameter;null, instead of a context-less NullReferenceException.

The inbound conversion creates the object and validates it. It does not throw for invalid data — it produces an object with notifications, and whoever receives it checks IsValid.

📝 Usage Examples

Validating on input

using Tooark.ValueObjects;

var cpf = new Cpf(dto.Cpf);
var email = new Email(dto.Email);

if (!cpf.IsValid || !email.IsValid)
{
  // ["Field.Invalid;Document", "Field.Invalid;Email"] — keys, not yet translated
  IEnumerable<string> errors = [.. cpf.Messages, .. email.Messages];

  return BadRequest(errors);
}

The messages come out as keys, not as final text. To return them translated, hand the notifications to the ResponseDto of Tooark.Dtos, which resolves the consumer's language:

var notifications = cpf.Notifications.Concat(email.Notifications).ToList();

// {"Errors": ["The Document field is invalid", "The E-mail field is invalid"], ...}
return BadRequest(new ResponseDto<string>(notifications));

Composing in an entity

using Tooark.Notifications;
using Tooark.ValueObjects;

public sealed class Person : Notification
{
  public Person(string name, string email, string cpf)
  {
    var nameVo = new Name(name);
    var emailVo = new Email(email);
    var cpfVo = new Cpf(cpf);

    // The value object notifications bubble up to the entity
    AddNotifications(nameVo, emailVo, cpfVo);

    if (IsValid)
    {
      Name = nameVo;
      Email = emailVo;
      Cpf = cpfVo;
    }
  }

  public Name Name { get; } = null!;
  public Email Email { get; } = null!;
  public Cpf Cpf { get; } = null!;
}

Searching with the normalized value

using Tooark.ValueObjects;

var title = new Title("Ação e Reação");

title.Value       // "Ação e Reação"
title.Normalized  // "ACAOEREACAO"

Invalid object as text

using Tooark.ValueObjects;

var cpf = new Cpf("111");

cpf.IsValid          // false
cpf.Number           // ""
cpf.ToString()       // "" — never null
$"document: {cpf}"   // "document: "

Working with a delimited string

using Tooark.ValueObjects;

DelimitedString tags = "csharp;dotnet;tooark";

tags.Values   // ["csharp", "dotnet", "tooark"]
tags.Value    // "csharp;dotnet;tooark"

DelimitedString others = new[] { "a", "b" };
string text = others;   // "a;b"

📋 Dependencies

🤝 Contributing

Contributions are welcome! Start with CONTRIBUTING.md — it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.

By participating you agree to the Code of Conduct.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If Tooark helps your projects, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the BSD 3-Clause License.