DEV Community: MiguelDevelopez

TellDontAsk and CQRS - Object Design Guide Summary 2

MiguelDevelopez — Tue, 27 Apr 2021 08:47:31 +0000

Welcome back to the second part of the Summary of Object design style guide by Matthias Noback, where I will try to synthesize the differences between query and command methods, CQS, TellDontAsk principle, and more things from the book.
And as for the first post, I highly recommend you to read the full book to find more examples in detail.

Let’s start!
There are two kinds of methods in an object, these are:

Retrieve a piece of information: getters, format, calc, “select” from the DB...
Perform tasks: sending an email, “update” or “delete” from the DB… You may know about the Command Query Responsibility Segregation (CQRS) principle, this principle is to define exactly what I was talking about (do not mix with the Command from CQRS with the Command Pattern ).

1º Retrieving information with query methods

To name these methods just call them what they are going to return or as the action, they are going to perform getting the information. Examples: itemCount, discountPercentage, calculateNetAmount, exchangeRateFor...
Query methods should have a single return type. You may still return null, but make sure to look for alternatives, like a null object, an empty list if your method will return an array, or throw an exception instead.
Here some examples:
BAD WAY, imagine what will be the code that receives this response.

/**
* @return string|bool
*/
public function isValid(string $emailAddress)
{
    if (/* ... */) {
        return 'Invalid email address';
    }
    return true;
}

There are many better ways to deal with it, but all of them have considerations:

Return a type or null.

public function findOneBy(string $type): ?Page { }
    $page = this->findOneBy($type);
    if (page instanceof Page) {
        // page is a Page object and can be used as such.
    } else {
        // page is null, and we have to decide what to do with it.
    }
}

Throw an exception and capture it in the client.

public function getById($id): User
{
    $user = User::find($id);
    if (!$user instanceof User) {
        throw UserNotFound->withId($id);
    }
    return $user;
}

Now the author talks about the good practice of not showing the internal functionality to the client, which reminds me of the principle Tell-Don’t-Ask, this principle encourages us to move behavior inside of an object, here an example:
BAD WAY

final class Product
{
     public function shouldDiscountPercentageBeApplied(): bool { }
     public function discountPercentage(): Percentage { }
     public function discountAmount(?Percentage $percentage): Money { }

     // Apply the logic and calculations in the client is not the best practice
}

// # main.php or Client.php or whatever
$product = new Product(...);
if($product->shouldDiscountPercentageBeApplied()) {
    $percentage = $product->discountPercentage();
    $money = $product->discountAmount($percentage);
} else {
    $money = $product->discountAmount();
}

$money->...

BETTER WAY

final class Product
{
     public function calculateFinalAmount(): Money
     {
        // use here the logic of the private methods, instead use them in the client
        // Let query methods expose as little of an object’s internals as possible.
     }
     private function shouldDiscountPercentageBeApplied(): bool { }
     private function discountPercentage(): Percentage { }
     private function discountAmount(?Percentage $percentage): Money { }
}

// # main.php or Client.php or whatever
$product = new Product(...);
$money = $product->calculateFinalAmount();
$money->...

In the bad way, the client has to use all the public methods to calculate the final amount of the product, so the client needs to know how to use the public methods, and that’s not the best solution.
With the better way, the client just has to call the calculateFinalAmount and it will execute all the logic, making this easier, decoupled, and centralized.

These recommendations should not become a rule that you can’t deviate from. In fact, no programming rule should ever be like that.

Query methods shouldn’t use command methods inside them to avoid having side effects. There are some exceptions, for example in a method of a controller, imagine a method that creates a user and returns it to the front, or some specific methods, for example, a method named nextId(), if two clients called this method at the same time it will return the same ID, so this method should make a side effect to avoid this potential error.

There are more tips related to the inversion dependencies and how to test with fakes or stubs, but I would like to deal with it in another different and specific post related to tests and the advantages of this practice.
Basically, when a query method needs to cross the system’s boundary (using DB, API call...) use an abstraction with an interface to be able to change and test it easily in the future.

2º Performing tasks with command methods

To name this kind of method the author recommends in the imperative form, for example, sendReminderEmail, saveRecord… and the command methods are easy to recognize because they always should return null.
But what happens if a command has to do more than one thing? Something like:

public function changeUserPassword(
    UserId $userId,
    string $plainTextPassword
): void {
    $user = $this->repository->getById($userId);
    $hashedPassword = $this->passwordHasher->hash($plainTextPassword);
    $user->changePassword($hashedPassword);
    $this->repository->save($user);
    $this->mailer->sendPasswordChangedEmail(userId);
}

First of all, as you can see there is no problem using a query method in a command method, and on the other hand, the changeUserPassword hides the fact that this method sends an email when a user changes the password, how can we deal with it properly? The best solution would be to dispatch an event, which allows us to have an object more decoupled, handle some effects in the background… but we have to take care and dispatch it explicitly to not lose track of where it is dispatched.
$this->eventDispatcher->dispatch(new UserPasswordChanged($userId));

As we do in the query methods, throwing an exception if something goes wrong is the best approach. You may be tempted to return a string in command, but remember that command must return null.

What should we do if a command needs to cross a system boundary (commands that reach out to some remote service, database, etc)? It’s the same as I mentioned in the queries, abstracting with interfaces. This will allow us to test command methods easily using a mock or a spy to test calls to these methods, avoiding sending emails or using the DB when the test runs. You can use a mocking tool for this or write your own spies.

3º Dividing responsibilities

In this chapter, the book talked about CQRS, the benefits, and why we should apply it. Personally, I think the CQRS will be overkill if your application won’t need to be maintained in a very long-term period (scalability matters), if the size is small or medium, simple user interface e.g. CRUD style, simple business logic…
In summary, CQRS allows you to separate the load from writes and reads allowing you to scale independently, for example, we’ll split a class like this:

final class PurchaseOrder
{
    private int $purchaseOrderId;
    private bool $wasReceived;
    private int $productId;
    private int $orderedQuantity;

    public function purchaseOrderId(): int
    {
        return $this->purchaseOrderId;
    }

    public function markAsReceived(): void
    {
        $this->wasReceived = true;
    }
    // ...
}

In a class for reading methods and another class for saving methods.
The class with command methods:

final class PurchaseOrder
{
    private int $purchaseOrderId;
    private bool $wasReceived;
    private int $productId;
    private int $orderedQuantity;

    public function markAsReceived(): void
    {
        this->wasReceived = true;
    }
    // ...
}

And to extract the query methods there are several ways to do that, for example:

Specific to a use case.
Directly from their data source.
Domain events.

Some advantages are:

Avoid exposing more behavior to a client than it needs.
Allow the read and write workloads to scale independently, and may result in fewer lock contentions.
The read side can use a schema that is optimized for queries, while the write side uses a schema that is optimized for updates

4º Changing the behavior of services

Some suggestions and recommendations about how to refactor a service. Some of these suggestions were covered before like, for example, use event listener for additional behavior, compose with abstractions (interfaces) to achieve more complex and easy to configure behavior because you will be able to replace instead of modifying the current one, introduce constructor arguments to make behavior configurable…
And something that I wanted to talk about in the first part… composition over inheritance.
The main reason for it is because with the inheritance you lose the flexibility and reconfigurability that brings to you the composition with interfaces. If you try to change the behavior of an existing object comes with many downsides:

Subclass and parent class become tied together, making your code more coupled, maybe with methods that you won’t use at all. Example: the typical BaseController.
Subclasses can override protected but also public methods, so a lot of the internals of the object are now exposed.

A better approach, according to the author, to reusing code is a trait. A trait is plain code reuse of a compiler-level copy/paste of code.

interface RecordsEvents
{
    public function releaseEvents(): array;
    public function clearEvents(): void;
}

trait EventRecordingCapabilities
{
    private array $events;
    private function recordThat(object $event): void
    {
        $this->events[] = $event;
    }
    public function releaseEvents(): array
    {
        return $this->events;
    }
    public function clearEvents(): void
    {
        $this->events = [];
    }
}

final class Product implements RecordsEvents
{
    use EventRecordingCapabilities;
    // ...
}

Don’t forget to close all your classes down for inheritance:

Mark them as final and make all properties
Methods private, unless they are part of the public interface of the class

And that’s all, I hope you enjoy it and the last part of this series will be published soon!

Sources and more info

Object Design Style Guide Summary

MiguelDevelopez — Tue, 16 Mar 2021 10:55:29 +0000

How you should create and use your objects

I’m currently reading an interesting book called Object Design Style Guide, wrote by Matthias Noback, about how to create objects as best as possible, so I decided to bring it up here and show you some tips and directives I found more interesting. Of course, I recommend you read the whole book if you want to go deep into this topic.

1º Introduction to some OOP concepts

In this book, inheritance plays a small role, even though it’s supposed to be one of the pillars of object-oriented programming. In practice, using inheritance mostly leads to a confusing design.
In this book, we’ll use inheritance mainly in two situations:

When defining interfaces for dependencies (dependency injection and inversion).
When defining a hierarchy of objects, such as when defining custom exceptions that extend from built-in exception classes. In most other cases we’d want to actively prevent developers to extend from our classes. You can do so by adding the final keyword in front of the class. It will be more explained later. The composition is highly recommended over the inheritance.

A little space to the test about that the basic structure of the unit test is:
The basic structure of each test method is Arrange - Act - Assert:
1 Arrange: Bring the object that we’re testing (also known as the SUT, or Subject Under Test) into a certain known state.
2 Act: Call one of its methods.
3 Assert: Make some assertions about the end state.

Shit's getting real. There are 2 types of objects:

Service objects that either perform a task or return a piece of information. Objects of the first type will be created once, and then be used any number of times, but nothing can be changed about them. They have a very simple lifecycle. Once they’ve been created, they can run forever, like little machines with specific tasks. These kinds of services are immutables. Service objects are do-ers, and they often have names indicating what they do: renderer, calculator, repository, dispatcher, etc.
Objects that will hold some data, and optionally expose some behavior for manipulating or retrieving that data, this kind is used by the first type to complete their tasks. These objects are the materials that the services work with. There are two subtypes: value objects and models/entities, but don't get ahead of ourselves.

2º Focus on Services

There is a pile of suggestions about how a service should be, I’ll make the list hiper-summarizing them:

To create a service use dependency injection to make the service ready for use immediately after instantiation and test double. So the dependencies should be declared explicitly. Here is an example of this, you can see how the parameter $appConfig is only used to get the directory of the cache so… Instead of injecting the whole configuration object, make sure you only inject the values that the service actually needs.

interface Logger
{
    public function log(string $message): void;
}

final class FileLogger implements Logger
{
    private Formatter $formatter;

    // Formatter is a dependency of FileLogger
    public function __ construct(Formatter $formatter) 
    {
        $this->formatter = $formatter;
    }

    public function log(string $message): void
    {
        formattedMessage = $this->formatter->format($message) ;
        // ….
    }
}

When possible you should keep together all the related configuration values that belong together. Service shouldn’t get the entire global configuration object injected, only the values that it needs.

WRONG WAY

final class MySQLTableGateway
{
    public function __construct(
        string $host,
        int $port,
        string $username,
        string $password,
        string $database,
        string $table
    ) {
        // ...
    }
}

GOOD WAY

final class MySQLTableGateway
{
    public function __construct(
        ConnectionConfiguration $connectionConfiguration,
        string $table
    ) {
        // $table is the name of the table, It isn’t necessary to make the connection 
    }
}

Avoid service locators (a service from which you can retrieve other services) and inject the dependencies that you need explicitly.
All the constructor arguments should be required because the code will be unnecessarily complicated. If you have the temptation to put it as an optional dependency you can use the null object.
Services should be immutable, that is, impossible to change after they have been fully instantiated because the behavior could be so unpredictable.

So... avoid something like this:

final class EventDispatcher
{
    private array $listeners = [];

    public function addListener(
        string $event,
        callable $listener
    ): void {
        $this->listeners[event][] = $listener;
    }
}

Only assign properties or throw exceptions because of some validation error in the constructor.

final class FileLogger implements Logger
{
    private string $logFilePath;

    public function __construct(string $logFilePath)
    {
        // $logFilePath should be properly set up, so we just need a safety check
        if (! is_writable($logFilePath)) {
            throw new InvalidArgumentException(
                'Log file path ’ . $logFilePath . ‘ should be writable’
            );
        }
        $this->logFilePath = $logFilePath;
    }

    public function log(string message): void
    {
        // ...
    }
}

Ideally, create objects to avoid the hidden dependencies, for example, the function json_encode() or a class from PHP like DateTime

WRONG WAY

final class ResponseFactory
{
    public function createApiResponse(array $data): Response
    {
        // json_encode is a hidden dependency
        return new Response(
        json_encode(
            $data,
            JSON_THROW_ON_ERROR | JSON_FORCE_OBJECT), ['Content-Type' => 'application/json']
        );
    }
}

GOOD WAY

final class JsonEncoder
{
    / **
    * throws RuntimeException
    */
    public function encode(array $data): string
    {
        try {
            return json_encode(
                $data,
                JSON_THROW_ON_ERROR | JSON_FORCE_OBJECT
            );
        // we can throw our own exception, with more specific info
        } catch (RuntimeException previous) {
            throw new RuntimeException(
                'Failed to encode data: ' . var_export($data, true),
                0,
                previous
            );
        }
    }
}

final class ResponseFactory
{
    private JsonEncoder $jsonEncoder;

    // JsonEncoder can be injected as a dependency
    public function __construct(JsonEncoder $jsonEncoder)
    {
        $this->jsonEncoder = $jsonEncoder;
    }

    public function createApiResponse(data): Response
    {
        return new Response($this->jsonEncoder->encode($data));
    }
}

And you can do the same with the date() and big core utilities of your language, and your application layer will be so decoupled.

3º other objects

3.1 value object and model/entity

The main suggestions are:

Validate the objects in the constructor, it will assure you that you only have valid objects in your application, every object will be what it was intended to be. You should throw exceptions in the constructor in case the data is not valid. The book suggests avoiding using custom exceptions for invalid argument exceptions, for this kind of RuntimeExceptions indicates that… more about it below.

final class Coordinates
{
    public function _construct(float $latitude, float $longitude)
    {
        if ($latitude > 90 || $latitude < -90) {
            throw new InvalidArgumentException(
                'Latitude should be between -90 and 90'
            );
        }
        $this->latitude = $latitude;
    }
}

Don't use property fillers, later we’ll see where you can use them with an example.
Entity/model should be identifiable with a unique id, value objects don’t because they only wrap one or more primitive-type values.
To add more semantic to a constructor the named constructors appear, those are static methods with domain-specific names that allow your code to have a better name than the typical new class().

Standard way

$salesOrder = new SalesOrder();

Better way

$salesOrder = SalesOrder::place();

You can put the __construct method as private to avoid using it and call the constructor inside the place() method.

final class DecimalValue
{
    private int value;
    private int precision;

    private function __construct(int $value, int $precision)
    {
        this.value = value;
        Assertion.greaterOrEqualThan($precision, 0);
        $this->precision = $precision;
    }

    public static function fromInt(
        int $value,
        int $precision
    ): DecimalValue {
        return new DecimalValue($value, $precision);
    }

    public static function fromFloat(
        float $value,
        int $precision
    ): DecimalValue (
        return new DecimalValue(
            (int) round($value * pow(10, precision)),
            $precision
        ):
    }
}

One of the best points of the value objects is that, if you validate in their constructor, when you see a value object you will know that it contains validated information and you will not have to validate this information in other points of the code.
Test the behavior of an object and the constructor in the way it will fail, don't create a test just to check if the values are correct.

public function it_can_be_constructed(): void
{
    $coordinates = new Coordinates(60.0, 100.0);
    assertEquals(60.0, $coordinates->latitude());
    assertEquals(100.0, $coordinates->longitude());
}

In summary, a value object does not only represent domain concepts. They can occur anywhere in the application. A value object is an immutable object that wraps primitive-type values.

3.2 DTO (Data transfer object)

The rules of 3.1 don't fit well with this type of object, the DTO. While in the value object and model we want consistency and validity of the data, in the DTO we just want (nobody expected it by the name) to transfer data from one point to another.

A DTO can be created using a regular constructor.
Its properties can be set one by one.
All of its properties are exposed, so make them public and access them directly without getters.
Its properties contain only primitive-type values.
Properties can optionally contain other DTOs or simple arrays of DTOs.
You can use property fillers when needed.

final class ScheduleMeetup
{
    public string $title;
    public string $date;

    public static function fromFormData(
        array $formData
    ): ScheduleMeetup {
        $scheduleMeetup = new ScheduleMeetup();
        $scheduleMeetup->title = $formData['title'];
        $scheduleMeetup->date = $formData['date'];

        return $scheduleMeetup;
    }
}

Well, the objects have methods where they contain the behavior, there are two kinds of methods, queries to retrieve information and commands to perform a task, but both of them could be designed with the same ‘template’, that is:
1º Checking parameters, throwing errors if there is something wrong.
2º Do what the method has to do, throwing errors if necessary.
3º Check postcondition checks. This won’t be necessary if you have good tests, but for example, if you are working with legacy code it could be good for safety checks.
4º Returns if is a query method.

You’ve seen that the exceptions are a good part of a code, some cases where using a custom exception is very useful:
1º If you want to catch a specific exception type higher up

try {
    // possibly throws ‘SomeSpecific’ exception
} catch (SomeSpecific $exception) {
    // …
}

2º If there are multiple ways to instantiate a single type of exception

final class CouldNotDeliverOrder extends RuntimeException
{
    public static function itWasAlreadyDelivered(): CouldNotDeliverOrder
    {
        // ...
    }
    public static function insufficientQuantitiesInStock(): CouldNotDeliverOrder
    {
         //...
    }
}

3º If you want to use named constructors for instantiating the exception

final class CouldNotFindProduct extends RuntimeException
{
    public static function withId(
        ProductId $productld
    ): CouldNotFindProduct (
        return new CouldNotFindProduct('Could not find a product with ID’ . $productld);
    }
}
throw CouldNotFindProduct .withId(/* ... */);

And you don’t have to put ‘Exception’ in the name of the exception class, instead, use explicit names like InvalidEmailAddress or CouldNotFindProduct.

And that’s all folks, there are soooo many more examples in the book, so I encourage you to take a look at it. If you want the second part of the book, let me know in the comments.

Sources and more info

TypeScript and why you should type your JS project

MiguelDevelopez — Tue, 02 Mar 2021 11:18:39 +0000

TypeScript is like JavaScript but with no surprises.

I heard a long time ago about TS, great stories about how useful it is, allowing js to have Javascript types. At this moment I wasn’t so 100% aware of the sense of type everything, now that I have more knowledge about clean code, good practices and start to develop some little applications in React I think that the code could be better with types and I decided to investigate about and… this is what I found:

🥰DEVELOPERS LOVE IT

Here are some charts about how people start to use more and more…

More interesting charts about JS here: https://2020.stateofjs.com/en-US/technologies/javascript-flavors/
Increasing the usage in GitHub projects.

https://octoverse.github.com/

And high place in the 2020 developer survey of StackOverflow:

https://insights.stackoverflow.com/survey/2020#technology-most-loved-dreaded-and-wanted-languages-loved
Big companies like Airbnb support its use and claim that using it would significantly reduce potential errors.

Source: https://twitter.com/swyx/status/1093670844495089664/photo/2

I went deep into Reddit to find some real words about it and the same: “It's very hard to go back to Javascript once you start writing Typescript”.

🚄But… WHY ALL THIS HYPE?

With so many people loving it I decided to learn the basics and this is what I have learned that it can offer.

Advantages:

SUPERSET of JS, almost the same language but with consistency in types.
The main advantage is strict typing, you can type everything, from variables to the parameters of a function, and even the structure of an object, that's can prevent about 15% of the bugs that end up in committed code.
The ability to find these obvious yet frequently occurring errors this early makes it a lot easier to manage your code with types.
Types make code management easier and more predictable.
In TypeScript we can define interfaces for parts of our program, so we can be sure that they interact correctly. It means they will have clear contracts of communication with each other which will significantly reduce the number of bugs. TS + unit tests will do the code more stable, predictable and it will reduce the amount of pre-release bug density.

But… Not all that glitters is gold...

Some little disadvantages:

Apply type may make you slower in the first instance, in the long term it is better but you have to get used to it.
Required compilation.
And of course, TypeScript does not catch run-time type errors. It means that you can write the code that will pass the type check, but you will get an error upon execution.

🤖 Examples of SYNTAX

Basic typing when you declare variables, you won't be able to change the type later (even if you don't declare strictly the type it will be typed), making your code more reliable:

If for any reason, you need a variable without specifically type you can use any:

But... in the documentation, they recommend not to use it unless you are in the process of migration from JS to TS.

Add enum to JS, a way of giving more friendly names to sets of numeric values:

Typing parameters of a function will allow you to detect quickly if you insert something wrong

You can add what is the type of function that will return

but if you don’t do it typescript will do it for you

You can create your own types that allow you to don't repeat the code.

You can type also what you select from the DOM, allowing you access to all the methods of one kind of input.

There are also interfaces, a contract that should be matched with the object if you don’t want errors, and other

And of course, you can implement TypeScript into your favorite JS framework, I'll show you an example in a React project, providing the same advantages mentioned above:

Similar to the PropTypes and now you will have to add the props as mandatory when you use them or the IDE will warn you:

And when you introduce the mandatory prop person it will be okay:

You will be able to type other things (practically everything) like, for example, the hook useState:

And that’s it, folks, I hope you enjoy this little piece of info about TypeScript and maybe consider applying it in some project.

Here are some sources and interesting videos to check and go deeper if you want:
JSConf - Airbnb tactics and strategy to migrate to TS (very interesting)
https://youtu.be/P-J9Eg7hJwE

To type or not to type: quantifying detectable bugs in JavaScript
https://blog.acolyer.org/2017/09/19/to-type-or-not-to-type-quantifying-detectable-bugs-in-javascript/

Official documentation - TS in 5min to JS developer:
https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html

TypeScript tutorial series:
https://www.youtube.com/playlist?list=PL4cUxeGkcC9gUgr39Q_yD6v-bSyMwKPUI
In this video, you can see how to apply TypeScript in React:
https://www.youtube.com/watch?v=Z5iWr6Srsj8