DEV Community: Alex Lawrence

Read Model on the write side

Alex Lawrence — Wed, 24 Mar 2021 19:46:40 +0000

This post explains why and how Read Models can be useful on the write side of a software. First, the terms CQRS, write side, read side and Read Models are briefly explained. Then, it is discussed how the read side works and why Read Models can also be used in other areas. Next, one common use case for read data on the write side is described. As last part, the whole topic is illustrated with a simplified example.

The many ways of CQRS

CQRS is a pattern that separates software into a write side and a read side. The idea is to treat write-related use cases differently from the ones that primarily yield data. However, the concept itself does not dictate any technological decision. Specifically, it does not demand to use separate data storages. Although this is a common setup, it is completely optional. Even the sole use of a caching mechanism or a view in an SQL database are some form of CQRS.

What is a Read Model?

A Read Model is a data structure for displaying information that is in some way based on a Write Model. The contained data may be denormalized, derived and even aggregated from multiple sources. Read Models can be expressed as concrete code components, but can also exclusively manifest as structural descriptions. Independent of a specific technological setup, a Read Model should be considered eventually consistent. This means, it must not be excepted to contain the most current state at all times.

Read side vs. Read Model

The read side of a software is responsible for executing read-related use cases. For this purpose, it typically maintains one or more Read Models. When a Query is issued to a responsible handler, the according read data is retrieved and returned. While Read Models are an integral part of a read side, they can also exist on a write side. Even more, there are certain use cases where the write side of a software should maintain its own Read Model.

Rules across Aggregates

One use case for a Read Model on the write side is the enforcement of a rule across transactional boundaries. Invariants protect individual Aggregates from entering an invalid state. On top of that, there can also be less critical rules that affect a collection of transactional boundaries. These constraints should normally be satisfied, but may be violated temporarily. For such scenarios, a Read Model can be used to provide the necessary information that is spread across Aggregates.

Example: Product reviewers

As example, consider a product review functionality of an e-commerce system. The rule is that one customer may only write one review for a single product. If this rule is considered an invariant, it demands that all reviews for a product share the same transactional boundary. Otherwise, it is impossible to satisfy the constraint at all times. However, enclosing all reviews for a product in one Aggregate results in a poor persistence performance and risks concurrency conflicts.

Reviewers Read Model

An alternative is to accept that the rule can be violated, as long as it is only temporary. This approach demands the ability to detect a violation and to perform a corrective action. Reviews are considered separate Aggregates and the write side can maintain a reviewers Read Model. For each product, there is a list of all customer reviews. When a Command for adding a new review is issued, the Read Model is used to decide whether this action is allowed.

Detecting the violation

For multiple concurrent review additions from a single customer, the Read Model may not be up to date. In such a case, the "one review per customer and product" rule can be violated. However, when the Read Model is synchronized, the violation can be detected. At this point, the software can report the issue or trigger a corrective action to remove extraneous reviews. Since a Read Model synchronization is ideally a matter of seconds, the temporary rule violation is negligible.

Here is some pseudo-code to demonstrate how the approach could be implemented:

class ReviewCommandHandlers {

  #reviewersReadModel; #reviewRepository;

  constructor({reviewersReadModel, reviewRepository}) {
    this.#reviewersReadModel = reviewersReadModel;
    this.#reviewRepository = reviewRepository;
  } 

  writeReview(command) {
    const {productId, reviewId, customerId, rating, comment} = command.data;
    if (this.#reviewersReadModel[productId][customerId])
      throw new Error('customer already wrote a review');
    this.#reviewRepository.save(new Review({id: reviewId,
      productId, customerId, rating, comment}));
  }

}

For each new review, the event "ReviewWritten" is published, which is used to update the Read Model:

class ReviewersReadModelSynchronization {

  #reviewersReadModel;

  constructor({reviewersReadModel, eventBus}) {
    this.#reviewersReadModel = reviewersReadModel;
    eventBus.subscribe('ReviewWritten', this.handleEvent.bind(this));
  } 

  handleEvent(event) {
    const {productId, customerId} = event.data;
    if (this.#reviewersReadModel[productId][customerId]) 
      console.log(`customer ${customerId} wrote multiple reviews for ${productId}`);
    this.#reviewersReadModel[productId][customerId] = reviewId;
  }

}

In this case, the synchronization component for the Read Model only reports the rule violation. As mentioned previously, another option is to trigger a corrective action.

Naturally, there are alternative approaches for enforcing a rule that spans across Aggregates. The important part here is to understand that Read Models are not exclusive to the read side of a software.

Buy my book "Implementing DDD, CQRS and Event Sourcing"
•
Discuss on Twitter

Originally published at https://www.alex-lawrence.com on March 24, 2021.

Insights from deep-diving into TypeScript

Alex Lawrence — Wed, 03 Mar 2021 19:58:44 +0000

This post summarizes some insights from my deep dive into TypeScript from when writing an appendix for my book. While I have been working with TypeScript for quite some time, most of the code I encountered was pretty trivial. The majority of the following aspects were new to me and helped me to understand the language better. Also, writing a lot of my book's code again in TypeScript allowed me to identify potential downsides.

Class magic

TypeScript has a special support for the class keyword. For every class within the global scope (of a module), it implicitly defines an instance type with the same name. This enables to write things like const user: User = new User(). Unfortunately, this mechanism does not work for dynamically created classes or plain constructors. In such cases, the behavior must be emulated with the utility InstanceType and the keyword typeof. Interestingly, export and import statements combine same-named values and types.

The following code illustrates this behavior:

class StaticClass {}
const a: StaticClass /* instance type */ = new StaticClass(); /* constructor */

const createClass = () => class {};
const DynamicClass = createClass(); /* no implicit type definition */
// this does not work yet: const b: DynamicClass = new DynamicClass();

type DynamicClass = InstanceType<typeof DynamicClass>; /* now there is a type */
const b: DynamicClass /* instance type */ = new DynamicClass(); /* constructor */

export {StaticClass, DynamicClass}; /* exports both constructors and types */

The statement type X = InstanceType<typeof X> is logically equivalent to what TypeScript does automatically when encountering the class keyword.

No type inference for members

For some implementations of an interface, the types of member attributes and member functions could be inferred. As example, when the interface Logger defines the function log(message: string): void, the implementation ConsoleLogger could just use the signature log(message). TypeScript could infer that the function parameter is a string and the return value is void. For different reasons, this is currently not supported. All member attributes and member functions must be typed explicitly, independent of interfaces or base classes.

The next example illustrates the potential repetition due to this circumstance:

interface Logger {
  logInfo(message: String): void;
  logWarning(message: String): void;
  logError(message: String): void;
}

class ConsoleLogger implements Logger {
  logInfo(message: String) { /* .. */ }
  logWarning(message: String) { /* .. */ }
  logError(message: String) { /* .. */ }
}

No partial type inference

TypeScript can infer the types for type parameters from their usage. For example, the function asArray<T>(item: T) { return [item]; } can be invoked without specifying the type parameter, such as asArray('foo'). In this case, T is inferred to be of type "foo" (which extends string). However, this does not work for multiple type parameters, where only some should be inferred. One possible workaround is to split a function into multiple, with one having all type parameters to infer.

The following code shows a generic function to create object factories with pre-filled data:

const createFactory1 = <R extends {}, P extends {}>(prefilled: P) =>
  (required: R) => ({...required, ...prefilled});
// requires to specify second type parameter, even though it could be inferred
const createAdmin1 = createFactory1<{email: string}, {admin: true}>({admin: true});
const adminUser1 = createAdmin1({email: 'john@example.com'});

const createFactory2 = <R extends {}>() => <P extends {}>(prefilled: P) =>
  (required: R) => ({...required, ...prefilled});
// first function specifies type parameter, for second function it is inferred
const createAdmin2 = createFactory2<{email: string}>()({admin: true});
const adminUser2 = createAdmin2({email: 'jane@example.com'});

The function createFactory1() requires to specify both type parameters, even though the second one could be inferred. The operation createFactory2() eliminates this issue by splitting the function into two individual operations.

Discriminating Unions usage

Discriminating Unions are useful for working with heterogeneous sets of similar items, such as Domain Events. The mechanism allows to distinguish between multiple types using a discriminating field. Every item type uses a specific type for the field that makes it distinct. When processing an item with a union type, its type can be narrowed down based on the discriminating field. One downside of this mechanism is that it requires the code to be written in a specific way.

The next example compares a JavaScript implementation of an event handler to its TypeScript counterpart with Discriminating Unions:

// JavaScript
const handleEvent = ({type, data}) => { // early destructuring
  if (type == 'UserRegistered')
    console.log(`new user with username: ${data.username}`);
  if (type == 'UserLoggedIn')
    console.log(`user logged in from device: ${data.device}`);
};

// TypeScript
type UserRegisteredEvent = {type: 'UserRegistered', data: {username: string}};
type UserLoggedInEvent = {type: 'UserLoggedIn', data: {device: string}};
type UserEvent = UserRegisteredEvent | UserLoggedInEvent;

const handleEvent = (event: UserEvent) => { // destructuring must not happen here
  if (event.type == 'UserRegistered')
    console.log(`new user with username: ${event.data.username}`);
  if (event.type == 'UserLoggedIn')
    console.log(`user logged in from device: ${event.data.device}`);
};

When using TypeScript, a value with a Discriminating Union type must not be destructured before narrowing down its type.

Template Literal types

Template Literal types are essentially Template Literals on a type level. They can be used to create string literal types that are the result of evaluating a template literal. The article "Exploring Template Literal Types in TypeScript 4.1" by David Timms explains them in greater detail with advanced examples. One notable use case is the definition of message processing components, where individual message types are handled by specific operations.

The following example demonstrates this using the previous logger example:

type MessageType = 'Info' | 'Warning' | 'Error';

type Logger = {
  [k in MessageType as `log${MessageType}`]: (message: string) => void;
}

class ConsoleLogger implements Logger {
  logInfo(message: String) { /* .. */ }
  logWarning(message: String) { /* .. */ }
  logError(message: String) { /* .. */ }
}

The type definition Logger iterates over the union type MessageType and defines one operation for each message type.

Don't let TypeScript get into your way

TypeScript is a powerful statically typed language. Many times, it is referred to as a "superset of JavaScript". However, for some functionalities, it forces to write code in a specific way. For one, Discriminating Unions influence how destructuring assignments can be used. Also, the lack of partial type inference can necessitate to split up one function into multiple ones. While the benefits of TypeScript likely outweigh its potential downsides, it is still important to be aware of them.

Discuss on Twitter

Originally published at https://www.alex-lawrence.com on March 3, 2021.

Domain Modeling by example

Alex Lawrence — Tue, 09 Feb 2021 10:52:45 +0000

This post illustrates a Domain Modeling process using a simple example. As first step, the actual problem is identified. Next, a solution approach is discovered. This is followed by the creation of an initial Domain Model. Afterwards, a first implementation is provided. Then, technical and logical challenges are discussed and solved. Also, the differences between a Domain Model and its implementation are explained. The post ends with a recommendation to use a problem-centric and model-driven approach, even for small projects.

Problem identification

Domain-Driven Design puts emphasis on the problems to solve and its involved knowledge areas. In my book, a Domain Model is defined as "set of knowledge abstractions that is focused on [..] solving specific problems". This means, in order to create a useful model, one needs to identify the problems first. As specific example, consider the following problem I encountered during the time when I was working on my book: I want to know the occurrences of individual words in a text.

At first, this statement seems useful. However, it is not really describing a problem, but already implying a specific solution. The relevant question is: What problem was I trying to solve with counting the occurrences of individual words? As I am not a native speaker, I am generally unsure about the diversity of my vocabulary. I wanted to somehow measure this aspect. Therefore, the real problem to solve that I had was to determine the vocabulary diversity of a text.

Solution approach

With the problem identified, one can decide on specific solution approaches. In my case, I was already settled on one. The idea was that I'd be able to determine the vocabulary diversity by looking at the occurrences of individual words. However, this approach implied that the software part alone is not a complete solution. Rather, it would only generate data that helps to derive indications of vocabulary use. Determining the actual diversity would be done by me as the user.

Initial Domain model

As mentioned previously, a Domain Model is a set of knowledge abstractions. Therefore, it does not have to have a specific manifestation or representation. Even more, while a model is commonly expressed in some way, the individual artifacts are often only subsets of information. For the vocabulary example, the knowledge abstractions can be conveyed through plain text. Note that this approach does not make any statement towards the complexity of the problem or the Domain Model.

The goal is to determine the degree of vocabulary diversity in a text. "Text" stands for a collection of words together with punctuation marks. "Vocabulary" can be defined as set of individual words. The term "diversity" incorporates the appearance of distinct words and their occurrences. The expression "degree" implies bounds and discrete steps between them. For the example, the vocabulary diversity is assumed to be a subjective metric that cannot be computed through software.

Altogether, the resulting Domain Model aspects can be summarized with the following points:

given a text, the vocabulary diversity should be determined
a text is a collection of words and punctuation marks
a vocabulary is a set of individual words
vocabulary diversity is a subjective metric that is determined manually

First implementation

After having the Domain Model defined, the implementation can be started. For the example, an iterative software development process is assumed. As a consequence, there are lower requirements in terms of completeness and correctness for the Domain Model. Rather, the above definition can be seen as initial draft that evolves further. Another way to understand it is that the following iterations are part of an experimentation phase without building production software.

The following code is the first implementation for counting the occurrences of individual words in a text:

const countWordOccurrences = text => {
  wordOccurrences = {};
  text.split(' ').forEach(word => {
    if (wordOccurrences[word] == null) wordOccurrences[word] = 0;
    wordOccurrences[word]++;
  });
  return wordOccurrences;
};

const wordOccurrences = countWordOccurrences(`This is a basic example.
  Also, this is only one of many possible examples.`);

console.log(wordOccurrences);
/* output: {
  This: 1, is: 2, a: 1, basic: 1, 'example.\n': 1, '': 1, 'Also,': 1,
  this: 1, only: 1, one: 1, of: 1, many: 1, possible: 1, 'examples.': 1
} */

The exemplary usage and its output demonstrate the capabilities of the initial solution.

Technical issues

There are some technical issues with the first implementation. These aspects are not due to flaws in the model, but related to correctly integrating implicit requirements into the code. One problem is that punctuation marks are mistakenly considered as part of a word. The same is true for newline characters. Another issue is that multiple whitespaces cause to create empty word entries. These aspects are ill-suited as explicit parts of the model, as they should be seen as common sense.

The following code provides a reworked implementation that overcomes the mentioned issues:

const wordRegex = /[a-z0-9]{1}[a-z0-9-]*/gi;

const countWordOccurrences = text => {
  wordOccurrences = {};
  Array.from(text.matchAll(wordRegex), match => match[0]).forEach(word => {
    if (wordOccurrences[word] == null) wordOccurrences[word] = 0;
    wordOccurrences[word]++;
  });
  return wordOccurrences;
};

const wordOccurrences = countWordOccurrences(`This is a basic example.
  Also, this is only one of many possible examples.`);

console.log(wordOccurrences);
/* output: {
  This: 1, is: 2, a: 1, basic: 1, example: 1, Also: 1, this: 1,
  only: 1, one: 1, of: 1, many: 1, possible: 1, examples: 1
} */

The second variant solves the mentioned technical issues by using a regular expression. This expression defines two rules. For one, every word must start with an alphanumerical character. Secondly, the first character can be followed by an arbitrary combination of alphanumerical characters and dashes.

Model refinements

The reworked implementation is an improvement, but still faces issues. There are problems that hint to flaws in the Domain Model. One is that the implementation is case-sensitive, which causes multiple entries for identical words with different casing. Another issue is that the singular and the plural form of one word are considered different things. Unlike the technical issues, these aspects should be explicit model parts. This is because they may be treated differently, depending on the problem statement.

The Domain Model definition can be updated as follows:

given a text, the vocabulary diversity should be determined
a text is a collection of words and punctuation marks
a vocabulary is set of individual words
vocabulary diversity is a metric that indicates the language quality
different casings of one word are considered the same
singular and plural of one word are considered the same

The final example provides an implementation that reflects the latest Domain Model:

const wordRegex = /[a-z0-9]{1}[a-z0-9-]*/gi;

const countWordOccurrences = (text, {asSingular}) => {
  wordOccurrences = {};
  text = text.toLowerCase();
  Array.from(text.matchAll(wordRegex), match => match[0]).forEach(word => {
    word = asSingular(word);
    if (wordOccurrences[word] == null) wordOccurrences[word] = 0;
    wordOccurrences[word]++;
  });
  return wordOccurrences;
};

const pluralize = require('pluralize');

const wordOccurrences = countWordOccurrences(`This is a basic example.
  Also, this is only one of many possible examples.`,
  {asSingular: pluralize.singular});

console.log(wordOccurrences);
/* output: {
  this: 2, is: 2, a: 1, basic: 1, example: 2,
  also: 1, only: 1, one: 1, of: 1, many: 1, possible: 1
} */

The case sensitivity is mitigated by making the input text lowercase. For the merging of singular and plural forms, the implementation introduces the dependency asSingular. This argument must be assigned with an operation that takes a word and returns the singular form. As example, the npm module pluralize is loaded and its function singular() is passed in as dependency. This approach ensures to express the model behavior correctly, while at the same time staying free of concrete dependencies.

Model versus code

There is a difference between a Domain Model and the knowledge an implementation expresses. Consider the following excerpt from my book: "An actual implementation may only reflect a subset of the underlying abstractions, and eventually deals with extraneous technical aspects." The vocabulary diversity example illustrates both statements. For one, the implementation does not express the full model, as it exclusively counts occurrences per individual word. Secondly, it also deals with purely technical issues such as multiple whitespaces or newline characters.

DDD for small problems

Another aspect this post illustrates is that allegedly simple problems can have a lot of complexity to them. Domain-Driven Design and its individual patterns are often recommended for large software projects with rich and complex Domains. However, starting with the problem space and creating a useful conceptual model before going into implementation is always beneficial. Even for a small functionality such as determining vocabulary diversity, a problem-centric and model-driven approach is valuable.

Buy my book "Implementing DDD, CQRS and Event Sourcing" • Discuss on Twitter

Originally published at https://www.alex-lawrence.com on January 20, 2021.

Using the filesystem for illustration purposes

Alex Lawrence — Mon, 08 Feb 2021 17:10:23 +0000

This post describes the approach of using the filesystem for illustrating the implementation of concepts related to persistence and messaging. Some of the explanations are put into the context of my book "Implementing DDD, CQRS and Event Sourcing". The approach is compared to the alternatives of using existing technologies as well as providing pseudo in-memory implementations. At the end, the post outlines the most relevant benefits and implications.

The approach

Apart from Node.js and JavaScript, my book does not explain or utilize specific frameworks or technologies. For all functionalities that require persistence or inter-process communication (IPC), it provides exemplary implementations that work with directly the filesystem. This includes Repositories, the Event Store, Read Model storages and an inter-process event distribution. The goal is to convey a deeper understanding of the concepts that are related to persistence and messaging. For production purposes, these implementations can be easily replaced with suitable technologies.

As example, the following snippet shows a basic variant of a generic filesystem-based Repository:

class FilesystemRepository {

  storageDirectory; #convertToData; #convertToEntity;

  constructor({storageDirectory, convertToData, convertToEntity}) {
    mkdirSync(storageDirectory, {recursive: true});
    Object.defineProperty(
      this, 'storageDirectory', {value: storageDirectory, writable: false});
    this.#convertToData = convertToData;
    this.#convertToEntity = convertToEntity;
  }

  async save(entity) {
    const data = this.#convertToData(entity);
    await writeFile(this.getFilePath(entity.id), JSON.stringify(data));
  }

  async load(id) {
    const dataString = await readFile(this.getFilePath(id), 'utf-8');
    return this.#convertToEntity(JSON.parse(dataString));
  }

  getFilePath(id) {
    if (!id) throw new Error('invalid identifier');
    return `${this.storageDirectory}/${id}.json`;
  }

}

The component can be used as base for specialized Repository components, such as the following:

class BookRepository extends FilesystemRepository {

  constructor({storageDirectory}) {
    super({storageDirectory,
      convertToData: entity => /* .. */,
      convertToEntity: data => new Book(data)});
  }

  async findBooksPublishedAfter(date) {
    const files = await readdir(this.storageDirectory);
    const ids = files.map(filename => filename.replace('.json', ''));
    const entities = await Promise.all(ids.map(id => this.load(id)));
    return entities.filter(book => book.publishingDate.getTime() >= date.getTime());
  }

}

The class FilesystemRepository is a generic Repository component that can be used as base class for arbitrary Entity types. As constructor arguments, it expects a storage directory as well as custom converter operations. These operations define how Entities are converted to data representations and vice versa. The class BookRepository is an example for a specific Repository that implements the domain-specific query findBooksPublishedAfter(). Apart from a small utility function, the base Repository is identical to the initial version in my book.

Notifications of filesystem changes can be achieved with the Node.js utility fs.FSWatcher. This component utilizes native system mechanisms to watch for filesystem events, such as inotify on Linux. While it is a powerful abstraction, it is not guaranteed to work for all systems and scenarios. Specifically, it does not work with shared filesystems, such as NFS. Nevertheless, it is a good choice for the illustration of certain concepts, such as event stream subscriptions or inter-process event publishing.

The following is a simple example for inter-process communication using the filesystem:

if (cluster.isMaster) cluster.fork();

const processType = cluster.isMaster ? 'master' : 'worker';

const ownInbox = `inbox-${processType}`;
await mkdir(ownInbox, {recursive: true});
fs.watch(ownInbox, async (event, filename) => {
  if (event !== 'rename') return;
  const message = await fs.promises.readFile(`${ownInbox}/${filename}`, 'utf-8');
  console.log(`message received in ${processType}: ${message}`);
});

await new Promise(resolve => setTimeout(resolve, 100));
const otherInbox = `inbox-${cluster.isMaster ? 'worker' : 'master'}`;
fs.promises.writeFile(`${otherInbox}/${Date.now()}`, `ping from ${processType}`);

The code spawns two independent processes. Each of them starts with creating its own inbox directory. Then, a filesystem watcher is configured to output the content of newly added files. Afterwards, each process writes a file into the inbox directory of the other one. Executing the code will output two messages that are sent across processes. While this example uses the cluster module, the programs could also be spawned in any other way.

Why not specific frameworks or technologies?

The use of specific frameworks or technologies for illustrating concepts related to persistence or messaging has both advantages and disadvantages. One benefit is the possibility to provide production-ready code. Furthermore, it allows to explain the used technologies, if that is a goal. However, there are multiple disadvantages. The use of specific tools inherently seems like a recommendation. Also, the reader requires more experience compared to when utilizing the filesystem. Finally, many technologies introduce an overhead, both in setup and use.

As example, consider my book would be using PostgreSQL as storage technology for an Event Store. In order to provide executable example implementations, the database setup would need to be explained. Also, reading the according code would require to understand SQL. Generally, PostgreSQL is a suitable candidate for an Event Store. However, there are also many other fitting databases. As always, the right choice of technologies depends on the specific use case. Therefore, implicit recommendations can in fact be counterproductive.

Build it yourself and throw it away

Attempting to build something yourself enables to gain a deep understanding of the associated concepts. With this approach, the goal is not to successfully build a production-grade functionality, but to learn as much as possible. In addition to a deep understanding of the concepts, one typically acquires the necessary knowledge to identify suitable existing technologies. Obviously, it is very subjective and generic to say that learning by building it yourself works well. Your individual experience may be different, of course.

For me personally, there were many occasions where this approach worked great. When I programmed with Turbo Pascal in my early adolescence, I tried to implement a 3D graphics engine. When I first worked as a freelancer, I built and used a small CMS, completely equipped with authentication and authorization. During my studies, I built a 2D physics engine in ActionScript/Flash. In the end, none of the projects were vastly successful. Nevertheless, my personal learning experience was second to none.

Why not a pseudo-implementation?

Another possibility for illustrating certain concepts is to provide a pseudo-implementation, such as an in-memory storage. While this can work, it is ill-suited for concepts related to persistence and inter-process communication. There are many challenges an in-memory functionality can simply ignore, such as transactions. Of course, these aspects can be simulated in some way, but the resulting implementations are likely to feel very artificial. Also, there are some concepts that simply require actual persistence, such as persistent Read Model projections.

As example, consider a minimal in-memory variant of the previously shown Repository component:

class InMemoryRepository {

  #storage;

  constructor() {
    this.#storage = new Map();
  }

  save(entity) {
    this.#storage.set(entity.id, entity);
  }

  load(id) {
    return this.#storage.get(id);
  }

}

The class InMemoryRepository is a Repository that stores Entities transiently. While its code is very short, it completely misses some crucial aspects. For one, it works synchronously, whereas actual persistence mechanisms are always asynchronous. Secondly, there is no data conversion, as the Map instance stores the actual objects. This practice can even lead to unexpected side effects, as the same reference objects are shared across all consumers. Overall, the class provides almost no abstraction over using a Map instance directly.

All the glitters is not gold

Using the filesystem for illustrating concepts related to persistence or messaging can be beneficial, but also has implications. Ideally, it enables to convey detailed knowledge. Also, it avoids technology preferences, does not require additional experience and can prevent overhead. At the same time, utilizing the filesystem for complex topics can feel like re-inventing the squared wheel. In the worst case, it produces more overhead than using an existing technology. Still, for the examples in my book it proved itself useful.

Buy the book • Discuss on Twitter

Originally published at https://www.alex-lawrence.com on December 29, 2020.

Why my book uses Node.js and JavaScript

Alex Lawrence — Thu, 04 Feb 2021 15:47:53 +0000

This post explains why I chose Node.js as runtime platform and JavaScript as programming language for my book "Implementing DDD, CQRS and Event Sourcing". The described reasons incorporate personal experience, the desired target audience, as well as platform and language characteristics. Also, the benefits and implications of static types are briefly discussed. Finally, the post closes with an outlook of future additions to the existing book.

Personal experience

One reason for using Node.js and JavaScript in my book is that I've worked with both for almost 8 years. As for JavaScript as a programming language, I have around 14 years of experience. Also, two projects in which I applied CQRS and Event Sourcing made use of those technologies. Therefore, it seemed like a natural choice for me when I planned to write a technical book.

Broad audience

Another reason for JavaScript is that it is a very widespread language, with which I can reach a broad audience. While not everybody may like it, there are many people who understand it. Also, its syntax can look similar to other languages, such as Java or C#, especially when using classes. While there are programming languages with distinct characteristics for specific purposes, the use of JavaScript simply enables a high reach.

As for syntax similarities, here is an exemplary Application Services class in JavaScript:

class NoteApplicationServices {

  #noteRepository;

  constructor({noteRepository}) {
    this.#noteRepository = noteRepository;
  }

  async createNote({noteId, content, category}) {
    const note = new Note({id: noteId, content, category});
    await this.#noteRepository.save(note);
  }

  /* .. */

}

The equivalent (blocking) implementation in Java merely differs in its type annotations:

public class NoteApplicationServices {

  private NoteRepository noteRepository;

  constructor(NoteRepository noteRepository) {
    this.noteRepository = noteRepository;
  }

  public void createNote(UUID noteId, string content, string category) {
    Note note = new Note(noteId, content, category);
    this.noteRepository.save(note);
  }

  /* .. */

}

This syntax similarity is also given for other programming languages, such as C# or PHP.

Universal language

My book contains a dedicated chapter on the User Interface part. There, I also use JavaScript for all client-side code. This is because it is natively supported in the browser and probably the most used language for web frontends. Furthermore, there is some universal infrastructure code that is consumed by both the server and the client. With this approach, the reader only needs to know one language in order to understand both backend and frontend code.

Platform simplicity

Over the years, I've worked with multiple languages, runtimes and servers for backends. Professionally, I used PHP and Apache, as well as C#, the CLR and IIS. When I started with Node.js, I was impressed by the minimal overhead for certain use cases. At the same time, it also felt suitable for building complex production-grade software, especially with selected third-party libraries. Overall, it made a good fit for the implementations in my book, which often serve an illustration purpose.

As an example, take a look at a simplified factory for creating an HTTP filesystem interface:

const createHttpFilesystemInterface = pathResolver =>
  async (request, response) => {
    const filePath = pathResolver(request);
    try {
      await stat(filePath);
      const fileExtension = path.extname(filePath);
      const contentType = contentTypeByExtension[fileExtension] || 'text/plain';
      response.writeHead(200, {'Content-Type': contentType});
      createReadStream(filePath).pipe(response);
    } catch (error) {
      response.writeHead(404);
      response.end();
    }
  };

const contentTypeByExtension = {
  '.js': 'application/javascript',
  '.html': 'text/html',
  '.css': 'text/css',
};

// example usage
const httpFilesystemInterface = createHttpFilesystemInterface(
  request => `${rootDirectory}/${url.parse(request.url).pathname}`);
http.createServer(httpFilesystemInterface).listen(50000);

This is not to exemplify that Node.js generally makes things simpler. However, there are many platforms where there is a lot more boilerplate code involved.

Concise and compact code

The code examples shown in my book must be compact. Especially in the PDF version, where there is a line length limit of 85 characters. For certain aspects, JavaScript enables to write concise and compact code. Often, this is the case for simple things due to the minimal overhead or ceremony. On top of that, there are certain language constructs that help to keep code short. Some examples are arrow function expressions, object literals, shorthand property names and destructuring assignments.

The below example shows the implementation of a simple Value Object type:

const Money = function({value, currency}) {
  Object.freeze(Object.assign(this, {value, currency}));
};

At first glance, the example may even look overly complex. One could also implement an arrow function that creates an anonymous object and freezes it. However, the above implementation is comparable to a full-blown class in a class-based language. The constructor function returns an instance that can be checked for its type. For example, the expression new Money({value: 10, currency: 'USD'}) instanceof Money evaluates to true.

What about types?

JavaScript is a dynamically typed language. Put the other way round, it lacks static typing. This can either be seen as advantage or as shortcoming. With regard to DDD and the modeling of complex domains, it is probably a disadvantage. The implementation of a complex Domain Model benefits from static typing and a powerful type system. For the examples in my book, the absence of types is in fact advantageous, as it keeps the code compact.

As example for the benefits of a powerful static type system, look at the following Domain Model implementation:

type Author = {id: UUID, firstName: string, lastName: string};
type Grade = 'A' | 'B' | 'C' | 'D' | 'E' | 'F';

type ExamResult = {author: Author, grade: Grade};

The type Grade expresses the domain-specific concept of a grade on type level. There are no runtime checks required for ensuring correct values. Apart from the Domain layer, other software parts may not benefit as much from static types. Also, trivial domain problems may be solved adequately with plain JavaScript. On top of that, there are possibilities for runtime type checking. Generally, the use of TypeScript has likely no disadvantages. At the same time, plain JavaScript can also be sufficient.

Why not something else?

There would have been many alternatives for a programming language and a runtime to use for my book. Node.js and JavaScript are generally not superior for applying DDD, CQRS or Event Sourcing. As mentioned, plain JavaScript can even be ill-suited for tackling complex domain problems due to the lack of static types. However, the two proved to be a fitting choice for my book. In the end, most of the example implementations can be easily mapped to other technologies anyway.

Plans for the book

While working on the book, I was sometimes concerned about not using TypeScript or even the overall choice of technologies. In order to ease my mind, I thought about future editions using TypeScript or even Rust without Node.js. As of now, I don't think that this is necessary. However, there is potential for useful future additions. My near-term plan is to either write an appendix on the benefits of types or to annotate existing affected content.

Buy the book • Discuss on Twitter

Originally published at https://www.alex-lawrence.com on December 21, 2020.

Why I wrote a book on DDD, CQRS and Event Sourcing

Alex Lawrence — Wed, 03 Feb 2021 15:24:16 +0000

This post explains my motivation for writing a book on DDD, CQRS and Event Sourcing. It starts with outlining how I came in contact with the concepts. Then, it describes how I first applied the patterns accidentally and afterwards worked with them extensively. Finally, it presents the initial book idea, my personal progress throughout the years and the actual result.

First contact

I first heard of Domain-Driven Design when I worked as a Senior Software Developer at AutoScout24. It was in 2012, when colleague developers told me about the concept and recommended "Domain-Driven Design" by Eric Evans. I immediately bought the book, but only skimmed it initially. Although I was working as a full-stack developer, I was primarily focused with UI development at that time.

Either also in 2012 or in 2013, I got introduced to CQRS and Event Sourcing. First, a few colleagues started to talk about the concepts. Some time later, Greg Young gave a workshop at AutoScout24. While I wasn't directly taking part, the workshop participants shared their gained knowledge with the rest of the department afterwards. Back then, I understood CQRS, but was concerned with the potential associated complexity. In contrast, I did not really grasp the idea of Event Sourcing.

Accidental application

Later in 2013, I started to work on a business idea with a good friend of mine. We built a Session Replay tool for UX testing purposes. In essence, the software recorded user interaction in the browser and reconstructed a video-like replay. There was a JavaScript snippet to include on websites that tracked the rendered HTML, AJAX calls and all user interaction. The data was sent to our Node.js backend and was exposed as playbacks through an according UI.

While I consciously defined a certain architecture for the software, it was merely a typical combination of MVC and ORM. At some point, it progressed from a monolithic software to a set of services. Only many months in, I realized that the software was applying some form of CQRS and Event Sourcing. On the write side, user interaction events were validated and persisted in a log. On the read side, those events were projected into a Session Replay.

Conscious application

In 2014, I started working for a startup that developed a collaborative web-based meeting software. There was a feature-complete prototype of the tool, which was already used in production. However, it faced various serious issues. The startup had decided to rewrite it completely in Node.js and to utilize selected patterns of DDD. As part of the overall software architecture, they also wanted to apply CQRS and Event Sourcing.

The startup developers were ambitious and talented. However, there was only limited theoretical knowledge and no practical experience with the concepts. Most had read the book from Evans and also recommended me "Implementing Domain-Driven Design" by Vaughn Vernon. Throughout the following year, I read both books multiple times and consumed everything I found online. This included the paper "CQRS Documents" and countless videos by Greg Young. Still, there were quite some unanswered questions on how to put everything into code.

In the end, we built a working software that applied tactical DDD patterns, CQRS and Event Sourcing. The implementation was backed by useful Domain Models. Personally, I acquired a lot of knowledge and practical experience. We even built a Node.js framework as byproduct. However, there were many mistakes, such as missing delivery guarantees or boundary violations. The overall inexperience was problematic. The software was effectively misused as playground for learning and applying patterns. This slowed down the project progress significantly.

Book idea

In 2016, before leaving the startup, I first thought about writing a book on implementing DDD, CQRS and Event Sourcing. I planned to use JavaScript and Node.js as an alternative to Java, which was used in comparable literature. Effectively, I wanted to write the book that the developers and I would have needed in the beginning. Although we acquired knowledge through the literature from Evans, Vernon and Young, we missed some guidance on the implementation part.

Personal progress

I worked on the book from the end of 2016 until the end of 2020, primarily as a side project. When I started, I was confident that I had all the required knowledge and experience. However, throughout the years, I learned many details, such as the conceptual difference between Domain Events and Event Sourcing records. Today, I know that I could not have written it at once in 2016 with the same quality.

Final result

The final book is quite different from what I envisioned it to be at first. Overall, it has much greater detail compared to what I had in mind in 2016. My initial goal was to write a short book with approximately 150 pages. The complete published version has now over 450 pages. However, I consider this a good thing. The book provides enough context to be read without any prior knowledge in DDD, CQRS or Event Sourcing.

Buy the book

Originally published at https://www.alex-lawrence.com on December 18, 2020.