DEV Community: Thomas Ferro

MongoDB query operators and arrays manipulation (M001 - Part 3)

Thomas Ferro — Tue, 29 Dec 2020 07:35:24 +0000

When exact matching is not enough.

We already covered the basic CRUD operations in the previous article. Before wrapping this section up, I would like to introduce more advanced concepts that are often used.

Comparing data

Until now, we almost exclusively search for documents by fields that should be strictly matching the provided query. This is far from the only type of comparison we use day to day.

Query operators: Tools to locale the requested data in a database.

All of the operators we will use begin with the $ sign.

For instance, here is how to use a query operator:

{ <field>: { <operator>: <value> } }

Here are some common operators to use:

$eq: "Equal to", for exact matching;
$ne: "Not equal to", for exclusion;
$gt: Match if the requested value is "greater than" the value provided in the query;
$gte: Match if the requested value is "greater than or equal to" the value provided in the query;
$lt: Match if the requested value is "less than" the value provided in the query;
$lte: Match if the requested value is "less than or equal to" the value provided in the query;

For instance, searching for a city with more than 10.000 citizens can look like this:

db.cities.find({ "citizens": { "$gt": 10000 } })

Looking for cities outside the USA can be done using this type of query:

db.cities.find({ "country": { "$ne": "USA" } })

Wait, what if I need to find the cities with more than 10.000 citizens, but outside of the USA at the same time? We will need to chain our statements to do so.

Chaining statements

Please do not stop reading, I promise that I am not going to hit you hard with the theory of logic gates.

You may find yourself in a situation where you want documents matching several statements. Sometimes you may need to match all of the statements, sometime at least one of them, or even none.

This is a common need in software development and it is also common when querying a database.

For instance, we can represent the rules behind a gas station serving a customer with the following statement:

const stationCanServeGas = customerPaymentAuthorized() && thereIsGasLeft()

MongoDB provides the tools to achieve the same goal using a different syntax and logic operators.

Logic operators: Tools to chain statement with specific behaviours

$and: The documents must match all of the provided statements;
$or: The documents must match at least one of the statements;
$nor: The documents must match none of the statements;
$not: Negates the provided expression.

The first three operators $and, $or and $nor have a similar syntax with an array of statements:

{ <operator>: [ { statement1 }, { statement2 }, ... ] }

The $not operator is completely different, please read through the documentation for more information about its behavior and syntax.

Going back to the first operators, we can for instance find every valid users by making a query with every needed matching:

db.users.find({
    "$and": [{
        "$or": [{
            "registrationCompleted": true
        }, {
            "ongoingRegistration": true
        }]
    }, {
        "ongoingDeletion": false
    }]
})

The $and operator is implicit by default, meaning that you can ignore it in order to simplify your requests. Here is the previous request using the implicit $and:

db.users.find({
    "$or": [{
        "registrationCompleted": true
    }, {
        "ongoingRegistration": true
    }],
    "$not": { "ongoingDeletion": true }
})

We can go even further with the implicit $and when doing multiple statements on the same field. Here are two ways of returning courses that take between 5 and 10 hours to complete:

db.courses.find({
    "$and": [{
        "estimateTimeToComplete": {
            "$gt": 5
        }
    }, {
        "estimateTimeToComplete": {
            "$lt": 10
        }
    }]
})

db.courses.find({
    "estimateTimeToComplete": {
        "$gt": 5,
        "$lt": 10
    }
})

As you can see, there are several ways to achieve the same goal. Some are more verbose or readable than others. It is up to you to make them maintainable and easy to understand!

Comparing fields within a document with the expressive query operator

Expressive query operator: Adds expressiveness to the query language by allowing us to use variables and conditions statements. It also allows for the use of aggregation expressions, discussed in a next article.

Here is the basic syntax of this type of operator:

{ "$expr": { <statement> } }

We can use the $ symbol inside of an expressive query operator to reference a document's field value.

Let us make this concept more concrete by seeing it in action. Here is how we can try to find cities that currently welcome more tourists than citizens:

db.cities.find({
    "$expr": {
        "$gt": ["$population", "$tourists"]
    }
})

Notice the change in the syntax, we will cover it in-depth when talking about the aggregation pipeline.

Querying and manipulating array fields

The MQL syntax offers many operators to query and manipulate arrays. We already used the $push operator in the previous article, here is a distilled explanation of it:

$push: Adds one or many elements to an array or turn the field into an array if it was of a different type.

Here is how we can add a student in a course:

db.courses.updateMany({
    "subject": "Mongodb"
}, {
    "$push": {
        "students": "Eliot Horowitz"
    }
})

To search for a document based on elements in an array, we can use several approaches:

When looking in an array with one provided element, no matter if there are other elements:

db.<collection>.find({ <the_array>: <one_of_the_element> })

When looking in an array with the exact list of elements provided:

db.<collection>.find({ <the_array>: [<the_first_element>, <the_second_element>, <...>] })

When looking in an array with the provided list of elements in any order:

db.<collection>.find({ <the_array>: { "$all": [<the_first_element>, <the_second_element>, <...>] } })

We also have the possibility to search for an array with a specified length using the $size operator. For instance, looking for courses with 10 students and with Eliot Horowitz, Kevin Ryan and Dwight Merriman could look like this:

db.courses.find({
    "students": {
        "$size": 10,
        "$all": [
            "Eliot Horowitz",
            "Kevin Ryan",
            "Dwight Merriman",
        ]
    }
})

One of the advanced tools for array querying is $elemMatch.

$elemMatch: Returns every document with the array field containing at least one element matching the query.

Let us say that our students in the courses collection are now complex objects with their name, age and other useful information in this context. For legal purpose, we want to find courses with at least one student under 18. We can achieve that with the following query:

db.courses.find({
    "students": {
        "$elemMatch": {
            "age": {
                "$lte": 18
            }
        }
    }
})

Another useful tool provided by the MQL allows us to search for a specific element in an array based on his index.

Say for instance that we want to get every courses where the first student is named "Merriman". We could achieve this goal using the following syntax:

db.courses.find({
    "students.0.name": "Merriman"
})

Leaner find results with projections

We can decide which fields to return in a query by specifying a projection.

db.<collection>.find({ <query> }, { <projection> })

With the projection being a set of key-value pairs with the value being 1 if we want the field to be included or 0 if we want it excluded. Note that you cannot mix zeros and ones in a single projection, except for the "_id" field that can be excluded in a projection with included fields.

For instance, if we only want the students and the subject of a course, we can define the following projection:

db.courses.find({}, {
    "subject": 1,
    "students": 1
})

Combining projections and query is also possible. Here is how we can use our previous query, but only return the subject of the matching courses:

db.courses.find({
    "students": {
        "$size": 10,
        "$all": [
            "Eliot Horowitz",
            "Kevin Ryan",
            "Dwight Merriman",
        ]
    }
}, {
    "subject": 1,
})

This article wraps the first part of the series regarding the MongoDB certification. It has been a long yet interesting journey! I hope that you are as eager as I am to cover basic cluster administration, the aggregation framework and the last subjects of the course 😁

A pragmatic approach to documents manipulation in MongoDB (M001 - Part 2)

Thomas Ferro — Tue, 08 Dec 2020 12:37:08 +0000

What do you value the most between a documentation exploring in-depth every aspect of a technology and a cheat sheet?

Biased question, I know. These two tools have different reasons to exists. My point is to make you think about ways to learn the basics of a technology without the unnecessary details. This state of mind can be helpful to tell if this technology fits your needs before consuming too much time in it.

The goal of this article is to provide you with the minimum knowledge required to get you as far as possible. The 20% knowledge that covers 80% of your daily use cases (totally made-up numbers, for the sake of the metaphor).

As it is often the case with engineering, the more advanced concepts will be built upon those bases. Make sure you master them!

Manipulate the whole database

We already discussed that the data are represented as documents in collections.

When manipulating data with MongoDB, we are manipulating JSON (Javascript Standard Object Notation). See this introduction if you never wrote JSON before or if you are looking for more information about the notation.

{
    "course": "MongoDB",
    "level": "M001",
    "information": {
        "titre": "Introduction to MongoDB",
        "description": "Your first tour of the NoSQL database's feature"
    },
    "attendees": [
        "Thomas Ferro",
        "John Doe"
    ]
}

JSON aim to be user-friendly and is already known by a great amount of developers. However, his text-based approach is space-consuming and limiting. MongoDB addresses these issues by compiling the data into the BSON (Binary JSON) format, optimized for speed, space and flexibility.

JSON can be used when wanting to export the data in a human readable form, where BSON should be preferred when making a backup for instance.

To Import and export your data, you will need your cluster's "srv URI" (secured uniform resource identifier) and one of the following command:

JSON:
- Export a collection as a JSON or a CSV file: mongoexport --uri <URI to your cluster> --collection=<collection name> --out=<your file>.json
- Import a collection from a JSON or a CSV file: mongoimport --uri <URI to your cluster> --out=<your file>.json (can have an additional argument with the targeted collection)
BSON:
- Export the content from a database as a binary file: mongodump --uri <URI to your cluster>
- Restore the database from a binary extract: mongorestore --uri <URI to your cluster> --drop <your_dump>

Here is an example of a URI:

mongodb+srv://<your username>:<your password>@<your cluster>.mongodb.net/<your database>

Please notice that the password is not mandatory to the URI, but you will be prompted to enter it if you do not set it there.

Explore your data from Atlas' UI

In a cluster, click on the "collections" button to access the view with every databases and collections.

The "Find" tab shows the currently selected collection's documents, filterable with the query filed above the documents. Queries must use valid JSON, we will be discussing more on that matter later.

You can see other tabs like "Indexes", which refer to more advanced concepts regarding MongoDB. We will cover them in future articles.

Explore your data from a terminal

Connect to the cluster from a terminal then use the find command.

First, show the cluster's databases with the command show dbs and choose the one to use with the command use your_database.

To view the collection in the selected database, enter the command show collections.

Get every document in a collection with the find command. For instance, in order to get every grade in the trainings collection, use db.trainings.find({}).

This command will only show you the first 20 documents. To continue exploring your collection, type the command it (to "iterate" through the cursor).

A cursor is the object returned by the find command, a pointer to a result set of your query.

In order to count every document, you can chain the .count() command in the previous query:

db.trainings.find({}).count()

You can also simply replace the find command with a count:

db.trainings.count({})

To view the results in a more readable format, use the pretty() method at the end of your command:

db.trainings.find({}).pretty()

Most of the time, you will need to query your data and not simply getting all of the document. To do so, we will fill the previously empty curly braces with what we need to look for, following the query syntax.

A good first example is to find documents with a field that matches a specified string. For instance, let us find every training regarding the subject of MongoDB:

db.trainings.find({ "subject": "MongoDB" })

You can also search for what are called sub-documents, nested JSON objects inside the document.

What if we want to find this course while only knowing his title, inside the information sub-document?

{
    "course": "MongoDB",
    "level": "M001",
    "information": {
        "titre": "Introduction to MongoDB",
        "description": "Your first tour of the NoSQL database's feature"
    },
    "attendees": [
        "Thomas Ferro",
        "John Doe"
    ]
}

We can do that by using the following notation:

db.trainings.find({ "information.title": "Introduction to MongoDB" })

When searching for data, you may need to limit the number or returned result or to sort them. We can do these actions by using the corresponding limit and sort methods.

Limiting the number of documents returned can be done by chaining a call to the limit method with the number of documents that you want after the find command:

db.trainings.find({ "subject": "MongoDB" }).limit(2)

Sorting looks pretty similar, but with a more complex syntax. You will need to specify every field that you want to use to sort. Each of those fields will have a value of 1 if you want an ascending sort or -1 if you want a descending one.

Searching for the least difficult training can be done using the following command:

db.trainings.find({  }).sort({ "difficulty": 1 }).limit(1)

There is a lot more to learn for querying data in MongoDB, like searching in arrays, comparing with booleans, numbers, partial matching and composition of queries.

However, I think that this is a good time to take a break from querying, now that we covered the basics of MongoDB. The training seems to be on the same page since the chapter ends here 😁

Add new documents

Through the Atlas UI

Here are the few steps required to insert a new document in your database.

Select a collection and click the "Insert document" button (directly writing a JSON or one field-value pair at the time).

The first thing that we see is an _id field populated with an ObjectId. Every document should have a valid identifier, but not specifically an ObjectID. For instance, if the best identifier for a citizen collection is his own identification number, feel free to use that.

You can specify your unique value or let MongoDB find one by using the ObjectId() method.

Then you can add as many field of the needed type as you want.

Through the shell

First, connect to your cluster from a shell and navigate to the database that you want to use with the use command.

We will use the insert method to add a new document. Here is a basic example creating a document with only a subject field in the "courses" collection:

db.courses.insert({
  "subject": "MongoDB"
})

The identifier (_id) is automatically assigned with a generated unique identifier if not provided.

This command should return the number of inserted documents.

Trying to create a document with an already declared identifier

Every document's ObjectID must be unique. When trying to add a document with an ObjectID that is already in the database, you will get a duplicate key error.

WriteResult({
    "nInserted" : 0,
    "writeError" : {
        "code" : 11000,
        "errmsg" : "E11000 duplicate key error collection: sample_training.zips index: _id_ dup key: { _id: ObjectId('5c8eccc1caa187d17ca6ed29') }"
    }
})

When importing data from a dump or an export, you may want to overwrite document with an already existing identifier. You can do so by using the --drop option.

Inserting many documents at once

One can insert several documents at once by passing an array to the command:

db.courses.insert([{
  "subject": "MongoDB"
}, {
  "subject": "Atlas"
}])

Again, this command returns the number of inserted documents and other useful information.

Error management when inserting many documents

When inserting many documents, MongoDB tries to insert them without modifying the provided order. This means that if the third documents out of a list of a hundred documents fails to insert, only the first two documents will be inserted.

You can prevent that behaviour if needed by adding the ordered option:

db.courses.insert([{
  "subject": "MongoDB"
}, {
  "subject": "Atlas"
}], { "ordered": false })

Updating a document

Through the Atlas UI

Once again, you will first need to connect to the Atlas UI and select the collection containing documents that you want to edit.

You can then filter this collection to find the documents to update or scroll through all of the documents.

Once you find the document to modify, click the "edit" button (the pencil) and start modifying the document as you wish.

This solution can work for punctually modifying a small amount of documents, but we will need the shell to perform more advanced and automated updating.

Through the shell

Update can be performed on one or many documents using respectively the updateOne and the updateMany commands. Both those commands have the same API, taking a query to find the documents to update as the first argument and update operators in MQL as the second argument.

First, we will try to update a single document. If several documents match the query, only the first one will be modified.

Here is how we could fix a typo in our MongoDB course:

db.courses.updateOne({
  "subject": "Mongodb"
}, {
  "$set": {
    "subject": "MongoDB"
  }
})

As expected when using updateOne, the command will only perform the update on the first matching document. To update every document matching the query, we will use updateMany:

db.courses.updateMany({
  "subject": "Mongodb"
}, {
  "$set": {
    "subject": "MongoDB"
  }
})

That operation was a basic one, but MongoDB provides a lot of update operators that can be used depending of your use cases. I highly recommend that you read through the documentation to get a grasp at what MongoDB can do while updating your data.

For instance, if we decide to add an array of students attending our courses, we can modify those students by using arrays update operators. Here is how we can add new students:

db.courses.updateMany({
  "subject": "Mongodb"
}, {
  "$push": {
    "students": { "$each": [ "Eliot Horowitz", "Kevin Ryan", "Dwight Merriman" ] }
  }
})

Here I pushed simple strings into the students array, but you can add any data structure you need.

The last thing I want to discuss regarding updating is the concept of upsert. When using this option, MongoDB will automatically create a new document if it does not find anyone matching your query. An ordinary update will be done if one or more documents match the query.

db.<collection>.updateOne({ <query_to_find_your_document> }, { <update_or_create_operation> }, { "upsert": true }); 
// Also works with updateMany

Deleting documents

Through the Atlas UI

Navigate to the collection with the documents to delete just like you did to update a document. Instead of clicking the edit button (the pencil), click the remove button (the bin). You can also delete a complete database or a collection by hovering them in the Data Explorer and clicking the corresponding remove button.

From the shell

You will once again be provided with two methods: one to remove a single document (deleteOne) and one to remove many documents (deleteMany). Consider using deleteOne only when deleting a document with a provided identifier, preventing you from only deleting one document when your goal was to remove every matching elements.

The first parameter of the delete methods if the same used in the find or update ones. You can use it to query the documents to remove. For instance, removing every "MongoDB" courses from our collection can be done using this command:

db.courses.deleteMany({
  "subject": "Mongodb"
})

Removing a collection can be done using the drop command:

db.courses.drop()

show collections
// The "courses" collection is no longer here

With this last section, we covered every basic database operations (CRUD operations for Create Read Update Delete). Next, we will see more advanced data manipulation.

Gentle introduction to MongoDB concepts (M001 - Part 1)

Thomas Ferro — Mon, 09 Nov 2020 13:01:34 +0000

Learn the intention before the implementation

I could have started this series by writing CRUD (Create / Read / Update / Delete) operations and explaining MongoDB base concepts on top of working example. However, I think that the best way to introduce a concept to some people is by allowing them to try along.

With that in mind, we will see what MongoDB actually is and how to get started with your own database for free!

Wherever there is data...

First of all, what is a database?

It is a structured way to store and access data. You usually need one when you need to persist any of your applications' data.

Take a note taking application for instance, where you can write and manage notes. Imagine the difference of provided value between those two versions:

One that loose all of your notes when refreshing the page;
Another one who allows you to retrieve your notes every time you start it.

This is a trivial example, but data is actually everywhere. I never had a single professional experience where no data was involved, have you?

There are two main families of databases usually used: the SQL and the NoSQL databases.

SQL actually refers to the Structured Querying Language, the language used to manipulate the data inside of a relational database management system (RDBMS). It also gave its name to the databases family of the same name.

Here are the main differences between the two kinds of databases.

SQL databases (OracleDb, PostreSQL, SQLite, ...): Where data is stored in strongly constrained and related tables.

NoSQL databases: Variety of database types that do not use the approach of related data tables.

In the NoSQL family, you can find:

Key–value stores (Redis for instance): Where data is stored as key-value pairs with the keys only appearing once in the database. Think of it as a map in your favorite programming language.

Document store (MongoDB): Where data is stored as documents in collections. We will of course discuss that kind of NoSQL database in length in this series.

Graph (Noe4j): Used for data with strong relationships. Think LinkedIn's relations web for instance.

These are the main types of NoSQL databases that you will encounter, but not the only ones.

So, MongoDB is a NoSQL document database, but what does it really means? Let us find out!

MongoDB basics

MongoDB is classified as a document database because of how it stores data. Every entry in your database will take the form of documents, representing your data as field-value pairs. Picture yourself a JSON object and you basically see a MongoDB document.

Want to stock user information? Here is a valid document:

{
  "firstName": "Thomas",
  "lastName": "Ferro"
}

Field: A unique identifier for the document's attribute.

Again, this is strongly similar to any JSON object where you cannot have the same attribute twice or more.

Are we supposed to throw all of our documents in a single spot and hope for the best when trying to retrieve valuable information? It is not the case since MongoDB offers a first level of data arrangement, the collections.

Collection: Where the documents are organized and stored.

The second level of arrangement are the databases. One database can have multiple collections and you will be able to search for your data by providing the couple database / collection.

For instance, the previous example can be stored in a users collection inside the database named after your project.

Different ways to host your database

It is time to get yourself an up and running MongoDB instance! We will see different way to have your own database, starting with solutions to run it locally.

I won't get into much details on this part, but I think that it can be useful to know how to get a local MongoDB instance for development or test purposes. You will have to main solution to do so.

This is not the way that I would recommend, but it is the most basic one. You can start a MongoDB Community Server by downloading it here.

If you are already familiar with Docker or trying to get better at it, I would recommend that you run a mongo container.

Both those solutions require you to manage the administration part, even though they can work out of the box for basic usage. This can suit you for starting and getting to know MongoDB. However, when starting a real project, I would recommend using a managed database.

Managed databases are MongoDB (or other solutions) instances provided by a third party. As a developer, I found this solution to be the perfect compromise. It allows me to focus on my field of expertise while resting assured that my data will not be corrupted or deleted because of my lack of operational skills.

In this case, we often talk about database as a service such as MongoDB Atlas or the solution provided on Amazon Web Services, Microsoft Azure or other. Those providers usually take responsibility for deploying, running and maintaining your MongoDB infrastructure with different pricing strategies.

In this series we will be using MongoDB Atlas since they are the ones providing the course and they offer a free plan for us to try their services.

MongoDB Atlas in theory

On top of the MongoDB concepts, Atlas add a few principles.

Clusters: Groups of servers that store data.

You can picture a cluster as Atlas's magic sauce that brings you all of the services related to your database.

In order to provide high availability and resiliency, Atlas use the concept of replica sets.

Replica set: Connected MongoDB instances that store the same data.

Replica sets are useful to provide a resilient infrastructure by replicate the data in all instances. If one instance goes down, the others can still provide access to your data.

Instance: Single machine running MongoDB in the cloud.

Atlas also provide tools to monitor your databases, but we will not cover them here.

With that theoretical section out of the way, it is time to play with Atlas!

Start using MongoDB Atlas

The first thing to do is to create a cluster through Atlas' web application and store some data in it.

You can sign in with the authentication method of your choice here, then create an organization which will contain your databases.

Inside this new organization, create a new project that will serve as a sandbox. You can build a free cluster in the cloud provider of your choice. It should not matter for this example, the Atlas services are supposed work the same for any cloud provider.

You now can serve yourself a cup of coffee or tea while the cluster is being provisioned for you ☕️

Congratulations, you have your first MongoDB cluster in the Cloud!

We now want to access the cluster. Two things to configure to do so:

Grand access to our IP address (more information on security features here)
- You can allow access from anywhere for now, but you really should define who can access your database before going into production.
Create a database user that will have the rights to perform actions on the data.

To start manipulating data, I suggest you load the sample dataset into your sandbox by clicking the ellipsis on your cluster then "Load sample dataset".

Visualize data

Click the "collections" button in the cluster to see the data stored in it. You should be able to navigate through the databases, collections and documents imported from the sample dataset.

If you want to access and manipulate your data through a shell, you first need to click the "connect" button in your cluster then "Connect with the mongo shell". Here you will find every needed information to download the tool if needed.

Enter the provided connection command line in your terminal, replacing dbname and dbuser with your database's information: mongo "mongodb+srv://sandbox.xsnoi.mongodb.net/<dbname>" --username <dbuser>.

You should be prompted to enter your user's password. Once done, you are connected to your cluster!

Try to use the db command to see the name of your database 😁

You now have your own sandbox, it is time to learn how to actually manipulate data.

Thanks for reading through, next time we will dive deep into documents creation and manipulation!

Take the road to MongoDB certification with me!

Thomas Ferro — Tue, 03 Nov 2020 07:33:12 +0000

Something about journeys and destinations

"Do you find value in passing certifications?"

Ask this question to me three years ago, I bet that my answer could have been one of the following:

"What will change in my day to day job if I had those certificates?"
"Why should I spend that much time for a piece of paper only valid for a few years?"
"Who are you all and what is that Coronavirus business you talk about?"

Ask the same question to me now and I will probably send you the link to this article. You know what they say about developers being lazy 🤷‍♀️

My experiences and the exchanges I had with my peers helped me understand some underlying concepts behind the simple piece of paper that is a certificate.

First, there is employability. Picture yourself as a recruiter, looking for the a senior software engineer with a strong experience regarding Javascript. You receive two résumés with more or less the same experiences, yet one of them is certified both for front-end and back-end Javascript frameworks. Who are you most likely to call first? I do not say that certifications are all that matter, but it can definitely help you get the job that you want.

Then there is the point that resonate the most with me. Preparing a certification puts you in a position where you need to dig deep into a specific subject. It is similar in that way to creating educational content. You need to become an expert on the subject and it exceeds the certificate itself.

Your certificate may not be valid anymore in a few years, but the acquired knowledge will last.

You may not know every piece of the most obscure APIs of the technology that you are learning, that is not the point. However, you will know what it is capable of doing and how to find the piece of information needed to put it in action!

Finally, certifications can be a good starting point when looking for valuable content for your technological watch.

Regarding MongoDB

MongoDB University is a learning platform providing many courses for you to learn how to make the best out of the NoSQL database. Whether you are a developer or a database administrator, you will find dedicated learning paths and even certifications.

I chose to follow the developer learning path to consolidate my skills. I used MongoDB with a bare minimum of knowledge for several years and I think that it is time to get the most out of this tool, both for professional and personal use.

The articles can be seen as many things, depending on what you are looking for. It can serve as a quick introduction to the concepts behind MongoDB, or event as additional content when preparing to take your own certificate. For me it is more like a log of my journey through the free training courses designed for developers.

I will try to make the articles as accessible as possible, assuming as little technological knowledge as possible when introducing concepts. Yet, I will certainly make parallels with other technologies for those already familiar with them. If you are not aware of those technologies, no worries! Take it as an opportunity to learn new fields 😉

Please share your experience regarding MongoDB and certification at large!

Internationalize your Svelte app with reactive stores

Thomas Ferro — Sun, 25 Oct 2020 09:34:57 +0000

You either pick a i18n library or live long enough to write your own

I must confess something to you, and I hope that you will forgive me for it: I am French 🇫🇷🥖🧀🍷🐸🇫🇷.

I tend to write my applications in English in order to make them accessible to the greatest number of developers around the world. However, I sometime forget about the people closest to me.

I recently asked my family to beta test an adaptation of a board game that I am building and the first feedback that I got was my girlfriend asking me "pourquoi c'est en anglais ?" ("why is your game in English?").

Fair point. I immediately added an issue on this subject and start thinking about how to internationalize the application. Oh, and for those who wonder what i18n means, it is a commonly used abbreviation for internationalization, where the eighteen characters between the i and the n are represented by the 18.

I already worked on that subject in my early days of Vue.js developer, using Kazupon's Vue I18n library. I loved the ease of use of the API, simply calling a $t method with the translation key in order to make everything work.

I wanted to find a Svelte alternative with the same appeal, but then think that it could make a great use case to learn to use a tool that I never practice before: the stores.

Again, I do not encourage you to build a new solution from scratch for every technical subject, especially when there is already well maintained alternatives. However, for now, let us learn how to use Svelte's stores to build a reactive internationalization mechanism 😁

Building the i18n mechanism

Practicing Test Driven Development has taught me something that I love to use when I have the opportunity, always starts by building the API that fits you the most. Only starts working on implementation details once the intention is clear.

Let us do just that and imagine the API of our dreams, starting with how to ask the system for a specific translation.

I like the idea of calling a simple method, directly from the template or from the <script>, something like this:

<script>
  import { i18n } from './i18n';

  // A localized message injected in the script
  $: authenticationErrorMessage = i18n('authenticationError')
</script>

<!-- A localized message directly called from the template -->
<h1>{i18n('welcomeMessage')}</h1>

<p>{authenticationErrorMessage}</p>

Obviously we will need a method to change the current locale, a method that will hopefully be able to change automatically every translation in the page without a refresh (spoiler alert: it will).

<script>
  import { i18n, changeLocale } from 'path/to/i18n';
</script>

<button on:click={() => changeLocale('fr')}>{i18n('switchToFrench')}</button>
<button on:click={() => changeLocale('en')}>{i18n('switchToEnglish')}</button>

We could use JSON objects to manage the translations, one file per locale for instance:

{
  "welcomeMessage": "Welcome!",
  "authenticationError": "Unable to authenticate...",
  "switchToFrench": "Switch to french",
  "switchToEnglish": "Switch to english"
}

Having already worked in large scoped projects, I know that the number of labels can grow pretty fast. It would be nice if we could allow for the use of nested objects.

<h1>{i18n('home.welcomeMessage')}</h1>

<!-- With the JSON formatted like this: 
{
  "home": {
    "welcomeMessage": "Welcome!"
  }
}
 -->

Knowing our expected behaviour, it seems that we need a reactive mechanism accessible from any component in our application. We can manage this by using a global store, but how to implement it in Svelte? Heck, what is a global store?

Read the fantastic manual!

Leaving the Svelte world for a paragraph or two, a store can be seen as a way to manage reactive data outside of a component. It is especially useful when a lot of components share logic for a given matter.

Take the connected user management for instance. You may have one component managing the authentication process, another one responsible for the display of the connected user information, another one who takes care of editing the profile, etc. They all play with the same data and they need to be informed when this piece of data changes to update themselves accordingly.

This is where you could be tempted to create a user store. I am too, so let us create it!

Svelte provide us with a module for creating stores. We can create:

readable stores: See them as read-only stores. I have no use case for them by now, but they must be useful since they are available 🤷‍♀️
writable stores: "Classical" stores, offering us ways to subscribe and unsubscribe to the data's changes and methods to actually modify the data.
derived stores: A store based on other stores. We will see a specific use case for our i18n mechanism.

Here is a minimalist user store:

import { writable } from 'svelte/store';

export const user = writable({});

I warned you, it is minimalist. Here is how you can consume and change this store's data:

<script>
  import { user } from 'path/to/user/store'

  let username 
  user.subscribe(newUserInformation => {
    username = newUserInformation.name
  });

  // Can be called when typing the name in an input for instance
  user.set({ name: 'Thomas Ferro' });
</script>

<h1>Welcome {username}!</h1>

Subscribing to a store can seem like a lot of busy work with this method. Svelte also provide a way to subscribe with a shortcut, prefixing your store name with $:

<script>
  import { user } from 'path/to/user/store'
</script>

<h1>Welcome {$user && $user.name}!</h1>

The complete API can be found, as always, in the documentation.

Here is one extra feature that I enjoy a lot: any object with a correctly implemented .subscribe and .unsubscribe and optionally .set methods can be considered as a store by Svelte. Kudo for being able to create a framework-agnostic module.

However, for the sake of simplicity and brevity, we will use the provided methods to create our stores.

Finally building something

We know what we want to build, we know how we are going to build it... Time to code!

The first thing we want is a store with the labels for the current locale. We can manage this by creating a writable store with the labels and a method changing this store's data according to the new locale:

import { derived, writable } from 'svelte/store';
import enLabels from './en.json';
import frLabels from './fr.json';

const labelsStore = writable(enLabels);

export const EN_LOCALE = "en";
export const FR_LOCALE = "fr";
export let currentLocale = EN_LOCALE;

export const changeLocale = (newLocale) => {
    if (newLocale === EN_LOCALE) {
        labelsStore.set(enLabels)
        currentLocale = newLocale
    } else if (newLocale === FR_LOCALE) {
        labelsStore.set(frLabels)
        currentLocale = newLocale
    }
}

One could use these exposed method and constants to make a local switcher:

<script>
  import { changeLocale, EN_LOCALE, FR_LOCALE } from './i18n';
</script>

<button on:click={() => changeLocale(FR_LOCALE)}>🇫🇷</button>
<button on:click={() => changeLocale(EN_LOCALE)}>🇬🇧</button>

As explained in the description of the targeted API, I do not want the developers to directly access the labelsStore. Instead, I want them to use an exposed method and provide a translation key.

How can we expose this store in a way that fits our expected API? Using a derived store! This derived store will be called i18n and will not return directly an object with the labels, but a function that takes the translation key as an argument and return the label:

import { derived, writable } from 'svelte/store';

// [...] labelsStore implementation

export const i18n = derived(labelsStore, (labelsForCurrentLocale) => {
    return key => labelsForCurrentLocale[key]
})

This way, when the labels store is updated, the i18n derived store is notified and update itself too, making the components who depends on it refresh their templates.

We now need to manage the nested objects. We can extract this logic and use it directly in the method returned by the i18n store:

import { derived, writable } from 'svelte/store';
import enLabels from './en.json';
import frLabels from './fr.json';

const labelsStore = writable(enLabels);

const OBJECT_PROPERTY_SEPARATOR = "."

const crawlLabelsToFindRequestedTranslation = (currentLabels, translationKey) => {
    const pathToFollowInLabels = translationKey.split(OBJECT_PROPERTY_SEPARATOR)
    let currentPositionInLabels = currentLabels
    for (let i = 0; i < pathToFollowInLabels.length; i++) {
        currentPositionInLabels = currentPositionInLabels[pathToFollowInLabels[i]]
        if (!currentPositionInLabels) {
            return translationKey
        }
    }
    return currentPositionInLabels
}

export const i18n = derived(labelsStore, (labelsForCurrentLocale) => {
    return (translationKey) => {
        if (!translationKey.includes(OBJECT_PROPERTY_SEPARATOR)) {
            return labelsForCurrentLocale[translationKey] || translationKey
        }
        return crawlLabelsToFindRequestedTranslation(labelsForCurrentLocale, translationKey)
    }
})

There we go, our i18n is fully implemented, let us use it in a component 😃

<script>
  import { i18n } from './i18n';

  // A localized message injected in the script
  $: authenticationErrorMessage = $i18n('authenticationError')
</script>

<!-- A localized message directly called from the template -->
<h1>{$i18n('welcomeMessage')}</h1>

<p>{authenticationErrorMessage}</p>

Notice the slight difference in the usage, we need to prefix the store's call with a $ to directly access the value and for this value to be reactive. See the documentation for more details on that matter.

Possible next steps

I do not think that I will continue to work specifically on the i18n mechanism since it already covers everything I needed in my application.

However, they are some possible improvements and new features.

I think that it could be great to manage the pluralization and the translation with parameters. For instance, when a translation takes a parameter that won't go in the same place for different languages.

A dynamic local management could add value too, so the core of the mechanism won't change when adding new managed language.

And of course, one could think that this mechanism could be a standalone library 😬

A last word

I learned a lot while building this i18n mechanism and writing this article. I think that it is the best kind of learning, picking a specific subject only when you actually need it. I do not have the time not the will to go through the entire Svelte documentation and make a project that mixes all of the framework's features.

I hope that you discovered something too!

Localization is a common need for a lot of applications. I think that it would be a blast to have the communities of every front-end frameworks work together on a framework-agnostic reactive internationalization mechanism, don't you? 😃

Emancipate yourself from Vuex with Vue 3's Composition API

Thomas Ferro — Thu, 27 Aug 2020 21:06:36 +0000

Is there still room for Vuex with Vue 3?

Before wrapping up this series about Vue 3 and the Composition API, I wanted to show you one last use-case that I found interesting. If you did not already, please take a look at my introduction of the Composition API so that you won't get lost with the syntax.

This article is especially for the people who have already learned Vuex and tend to use it in every place where they manage data.

If you do not fit into this category or do not even know what Vuex is, here is a concise introduction.

One store to rule them all

According to the documentation, Vuex is "a state management pattern + library for Vue.js applications". Think of it as the place to store and manipulate reactive data outside of a component before we had the Reactivity and the Composition APIs.

I cannot recommend you enough to watch Vue Mastery's introduction on the subject, available on the library's home page.

To sum up greatly, you can use this library to externalize reactive data shared by components far from each other in the components tree.

Instead of communicating by sending props down the tree and emitting events up, you can use a Vuex store. This way, your components are always up to date when one of them modify the store's state.

These two schemas are from Vue Mastery's introduction. First you can see a complex component tree with a lot of events and props to manage in order to make the two leaf components communicate:

Here we use a Vuex store to simplify this communication:

A Vuex store is composed of these different parts:

state: The place where your reactive data lives. You cannot directly modify the state. To do so, you have to commit mutations;
getters: Just like computed properties, this is a way to expose the state in a different shape. They are usually used to avoid rewriting logic inside every component consuming the store;
mutations: The only way to modify the state is by committing mutations. They should be synchronous and the smallest possible;
actions: For asynchronous treatments or for logic that implies modifying many elements in the state, we can dispatch actions;
modules: In order to split the state, we can create stand-alone stores, the modules.

The state is represented as a stack of mutations that you can replay or just analyze in-depth:

This is just a theoretical introduction and it is not enough to get started. Please read through the documentation for more information.

My issue with Vuex

Vuex is just like any technology, it comes with a cost. First, the price of learning the library. It usually takes me half a day to only introduce the subject in the trainings that I gave. You can add a couple of days of practicing before actually tame the beast.

Secondly, when using Vuex, you tend to lost the concept of data responsibility. No component is responsible for the data when everyone can modify the store's state. This way of thinking usually leads to application that are hard to maintain and debug. It is hard to keep track of whom did the mutations and why, even when using great tools such as Vue Devtools.

When I say "usually", I generalize on purpose. They are applications where Vuex is used pragmatically and where the code base is still easily maintainable and scalable. However, I tended to overuse Vuex when I first learned it and I think that I am not the only one.

My take is to almost never use Vuex, especially when a simple "Parent-Child" communication pattern is enough. You will save yourself from long hours of debugging and headaches.

Where to use it, then? There are use-cases where it comes handy. Or should I say "where it used to came handy", now that we have the Composition API. Let me explain with an example, a sample application with user information displayed and editable.

User data management using Vuex

I will not be covering Vuex installation in this article, please follow the documentation if you need to.

Let us first take a look at what we will be building. We are not creating an entire Web application, it is way out of this article's scope. We will, however, build common pieces that you will certainly encounter if you have not already. Those two pieces are the following:

A Header component, displaying the user nickname and his profile picture;
A UserSettings component where the data will be editable.

Here, using Vuex is overkill. Just imagine that the rest of the application is ignored, that we have a complex component tree and Vue Router installed.

The actual API call will be externalize in the api.js file. Just know that it returns a Promise, like fetch or axios would have.

Let us start our implementation with the store's user module:

import { loadUserInfo, saveNewUserInfo } from './api';

const AVAILABLE_STATUS = {
    LOADING: 'LOADING',
    UPDATING: 'UPDATING',
    ERROR: 'ERROR',
};

export const user = {
    namespaced: true,
    state() {
        return {
            nickname: '',
            pictureUrl: '',
            status: '',
        };
    },
    getters: {
        isLoading: state => state.status === AVAILABLE_STATUS.LOADING,
        isUpdating: state => state.status === AVAILABLE_STATUS.UPDATING,
        errorOccurred: state => state.status === AVAILABLE_STATUS.ERROR,
    },
    mutations: {
        changeStatus(state, newStatus) {
            state.status = newStatus;
        },
        changeNickname(state, newNickname) {
            state.nickname = newNickname;
        },
        changePicture(state, newPicture) {
            state.pictureUrl = newPicture;
        },
    },
    actions: {
        // Called by the "App" component to ensure that the initial data are loaded
        load({ commit }) {
            commit('changeStatus', AVAILABLE_STATUS.LOADING);
            loadUserInfo()
                .then(({ nickname, pictureUrl }) => {
                    commit('changeNickname', nickname)
                    commit('changePicture', pictureUrl)
                    commit('changeStatus', '');
                })
                .catch(() => {
                    commit('changeStatus', AVAILABLE_STATUS.ERROR);
                })
        },
        update({ commit }, newUser) {
            commit('changeStatus', AVAILABLE_STATUS.UPDATING);
            saveNewUserInfo(newUser)
                .then(({ nickname, pictureUrl }) => {
                    commit('changeNickname', nickname)
                    commit('changePicture', pictureUrl)
                    commit('changeStatus', '');
                })
                .catch(() => {
                    commit('changeStatus', AVAILABLE_STATUS.ERROR);
                })
        },
    },
};

Here we have two important things. First, the state to consume with the nickname and the picture's url. We also have the possibility to modify the profile thanks to the update action.

A loading status is also managed in the store, which allows components to display the appropriate message to the user.

The header component can now consume the store's data:

<template>
    <header>
        <template v-if="isLoading">
            User information are loading
        </template>
        <template v-else-if="isUpdating">
            User information are updating
        </template>
        <template v-else-if="errorOccurred">
            Unable to manage user information
        </template>
        <template v-else>
            Welcome {{ nickname }}
            <img :src="pictureUrl" alt="User picture" class="user-picture">
        </template>
    </header>
</template>

<script>
import { mapState, mapGetters } from 'vuex';

export default {
    name: 'app-header',
    computed: {
        ...mapState({
            nickname: state => state.user.nickname,
            pictureUrl: state => state.user.pictureUrl,
        }),
        ...mapGetters({
            isLoading: 'user/isLoading',
            isUpdating: 'user/isUpdating',
            errorOccurred: 'user/errorOccurred',
        }),
    },
}
</script>

<style >
.user-picture {
    height: 40px;
    width: 40px;
    border-radius: 50%;
}
</style>

Last, the UserSettings component will do just the same and will use the action when the user validate his modifications:

<template>
    <form @submit.prevent="updateUser">
        <label>
            Nickname
            <input type="text" v-model="newNickname">
        </label>
        <label>
            Picture url
            <input type="text" v-model="newPicture">
        </label>
        <input type="submit" value="Validate changes" :disabled="formDisabled">
        <p v-if="errorOccurred">An error has occurred while managing user information...</p>
    </form>
</template>

<script>
import { mapState, mapGetters } from 'vuex';

export default {
    name: 'user-settings',
    data() {
        return {
            newNickname: '',
            newPicture: '',
        };
    },
    computed: {
        ...mapState({
            nickname: state => state.user.nickname,
            pictureUrl: state => state.user.pictureUrl,
        }),
        ...mapGetters({
            isLoading: 'user/isLoading',
            isUpdating: 'user/isUpdating',
            errorOccurred: 'user/errorOccurred',
        }),
        formDisabled() {
            return this.isLoading || this.isUpdating
        },
    },
    watch: {
        nickname: {
            handler() {
                this.newNickname = this.nickname;
            },
            immediate: true,
        },
        pictureUrl: {
            handler() {
                this.newPicture = this.pictureUrl;
            },
            immediate: true,
        },
    },
    methods: {
        updateUser() {
            if (!this.formDisabled) {
                this.$store.dispatch('user/update', {
                    nickname: this.newNickname,
                    pictureUrl: this.newPicture,
                })
            }
        },
    },
};
</script>

One can say that this solution works and he would be right. However, I see several drawbacks:

We need to make a component responsible for the initial data load;
A complete and complex library is needed for what seems to be a simple task.

Will the results be any better with the Composition API? Let us see!

The same result with the Composition API?

Refactoring this application to use the Composition API should not take too long.

First, we will create the ES module that will replace our store. How can we make a module that share the data between every consumers? We can use the singleton design pattern:

import { ref, computed } from "vue";

import { loadUserInfo, saveNewUserInfo } from './api';

const AVAILABLE_STATUS = {
    LOADING: 'LOADING',
    UPDATING: 'UPDATING',
    ERROR: 'ERROR',
};

// These data will only be created once and thus be shared by the consumers
const nickname = ref('');
const pictureUrl = ref('');
const status = ref('');

// Computed properties based on the status
const isLoading = computed(() => status.value === AVAILABLE_STATUS.LOADING);
const isUpdating = computed(() => status.value === AVAILABLE_STATUS.UPDATING);
const errorOccurred = computed(() => status.value === AVAILABLE_STATUS.ERROR);

// No need for mutations anymore, we can simply create JS methods
const apiCallReturnedWithNewUserInformation = ({ nickname: loadedNickname, pictureUrl: loadedPictureUrl }) => {
    nickname.value = loadedNickname;
    pictureUrl.value = loadedPictureUrl;
    status.value = '';
}
const load = () => {
    status.value = AVAILABLE_STATUS.LOADING;
    loadUserInfo()
        .then(apiCallReturnedWithNewUserInformation)
        .catch(() => {
            status.value = AVAILABLE_STATUS.ERROR;
        });
};

const update = (newUser) => {
    status.value = AVAILABLE_STATUS.UPDATING;
    saveNewUserInfo(newUser)
        .then(apiCallReturnedWithNewUserInformation)
        .catch(() => {
            status.value = AVAILABLE_STATUS.ERROR;
        })
};

// Fetch the user info when the module will be used for the first time
load();

// Export a method that returns every needed piece of information
export const useUserManager = () => ({
    load,
    update,
    nickname,
    pictureUrl,
    status,
    isLoading,
    isUpdating,
    errorOccurred,
});

Next, we need to change the way we consume data in our components:

<template>
    <header>
        <template v-if="isLoading">
            User information are loading
        </template>
        <template v-else-if="isUpdating">
            User information are updating
        </template>
        <template v-else-if="errorOccurred">
            Unable to manage user information
        </template>
        <template v-else>
            Welcome {{ nickname }}
            <img :src="pictureUrl" alt="User picture" class="user-picture">
        </template>
    </header>
</template>

<script>
import { useUserManager } from './user/userManager';

export default {
    name: 'app-header',
    setup() {
        const userManager = useUserManager();
        return {
            pictureUrl: userManager.pictureUrl,
            nickname: userManager.nickname,
            isLoading: userManager.isLoading,
            isUpdating: userManager.isUpdating,
            errorOccurred: userManager.errorOccurred,
        }
    },
}
</script>

<style >
.user-picture {
    height: 40px;
    width: 40px;
    border-radius: 50%;
}
</style>

<template>
    <form @submit.prevent="updateUser">
        <label>
            Nickname
            <input type="text" v-model="newNickname">
        </label>
        <label>
            Picture url
            <input type="text" v-model="newPicture">
        </label>
        <input type="submit" value="Validate changes" :disabled="formDisabled">
        <p v-if="errorOccurred">An error has occurred while managing user information...</p>
    </form>
</template>

<script>
import { ref, computed, watchEffect } from 'vue';
import { useUserManager } from './userManager';
export default {
    name: 'user-settings',
    setup() {
        const newNickname = ref('');
        const newPicture = ref('');

        const userManager = useUserManager();
        const formDisabled = computed(() => {
            return userManager.isLoading.value || userManager.isUpdating.value;
        });

        watchEffect(() => newNickname.value = userManager.nickname.value);
        watchEffect(() => newPicture.value = userManager.pictureUrl.value);

        const updateUser = () => {
            if (!formDisabled.value) {
                userManager.update({
                    nickname: newNickname.value,
                    pictureUrl: newPicture.value,
                });
            }
        }

        return {
            newNickname,
            newPicture,
            pictureUrl: userManager.pictureUrl,
            nickname: userManager.nickname,
            isLoading: userManager.isLoading,
            isUpdating: userManager.isUpdating,
            errorOccurred: userManager.errorOccurred,
            formDisabled,
            updateUser,
        }
    },
};
</script>

Finally, you can delete the store's files and remove the dependency from your application!

We now have the same result for the end-user, but our application does not depend on a library other than Vue.

I have to say, however, that this is not a silver bullet. Your application will still be hard to debug and maintain if you put everything into one big module. The Composition API is a tool, a great one, but still nothing more. It can do much more harm than good if used non-pragmatically.

What we built can be seen as - and is, actually - a simple State Management Pattern. We did leverage the clarity and modularity provided by the Composition API to create what I think is the most developer and user-friendly State Management Pattern.

Something ends...

What do you think about this State Management Pattern? Will you consider using it in your application?

It was the first time that I write so much about a single subject. I hope that you have learned as much as I did along the way :)

Please send me feedback about the series and your experiences, I will be glad to read from you all!

Composition API v Renderless Components - Let's use Vue 3's features to clean our components!

Thomas Ferro — Wed, 26 Aug 2020 11:59:55 +0000

Iteratively and incrementally improve components quality

Making the perfect component in the first draft is impossible. Impossible because you do not know exactly what will be needed before actually building the component. Impossible also because you will always learn new, more effective ways of doing things.

Too many times have I overengineered, trying to make components that no one would ever need to modify or fix, components that was meant to meet all present and future use cases.

Let me tell you the best place that I found for those components: in a post-mortem.

Why is he telling me all that, you may ask yourself. I wanted to introduce this article with this little digression to discuss the importance of iterations.

First, build the minimum viable product, the basic implementation that works and does what is expected. Only then starts the refinement phase to ship a clean and maintainable code.

You do not know if you are building the right thing until you try it. Ship it fast and get feedback.

It is a concept you should be familiar with when doing TDD or even if you recognize yourself in the Agile values.

This article follows the same pattern, we will start with a component that works, even though it is far from being maintainable. Then we will incrementally improve it, without the new Composition API in the first place so we will be able to compare with previously existing tools.

I will not discuss the mostly important matter of tests in this article. The reason being that I am not confident enough on the subject of Front-End testing to give you my opinion. I might dig into the subject in the future, but for now I leave you with a few resources:

Vue Test Utils - the official unit testing utility library for Vue.js;
Testing Library - a collection of utilities that encourage "good" testing practices. I haven't tried it yet, but the promise is good enough for me to share it with you.

The legacy component

Before starting any refactoring, we need to understand what we are working with.

We will be creating a TODO-list with only a few features:

Listing the tasks to do;
Creating a new task;
Tag a task as finishing.

The first thing we want to do is to make the application work, so let us do it!

<template>
    <h1>My TODO list! ({{ doneCount }} / {{ totalCount }})</h1>

    <!-- Error management -->
    <p v-if="loadingError">
        {{ loadingError }}
        <button @click="loadTodos">Reload</button>
    </p>

    <ul v-else>
        <li v-for="todo in todoList" :key="todo.id">
            {{ todo.content }}
            <button @click="achieveATodo(todo.id)">Validate</button>
        </li>
    </ul>
    <form @submit.prevent="() => addTodo(newTodoContent)">
        <label>
            What do you have to do?
            <input v-model="newTodoContent">
        </label>
        <input type="submit" value="Create">
        <!-- Error management -->
        <p v-if="todoCreationError">{{ todoCreationError }}</p>
    </form>
</template>

<script>
export default {
    name: 'todo-list',
    data() {
        return {
            loadingError: '',
            todoList: [ ],
            newTodoContent: '',
            todoCreationError: '',
        };
    },
    computed: {
        doneCount() {
            return this.todoList.filter(todo => todo.done).length;
        },
        totalCount() {
            return this.todoList.length;
        },
    },
    methods: {
        loadTodos() {
            this.loadingError = '';
            fetch(import.meta.env.VITE_TODOS_URL)
                .then((response) => {
                    if (!response.ok) {
                        throw new Error('An error has occurred while loading todos');
                    }
                    return response.json();
                })
                .then((todos) => {
                    this.todoList = todos;
                })
                .catch((error) => {
                    this.loadingError = error;
                });
        },
        achieveATodo(id) {
            // [...] Call the API to achieve the task
        },
        addTodo(content) {
            this.todoCreationError = '';
            fetch(import.meta.env.VITE_TODOS_URL, {
                method: 'post',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ content })
            })
                .then((response) => {
                    if (!response.ok) {
                        throw new Error('An error has occurred while creating todo');
                    }
                    return response.json();
                })
                .then((newTodo) => {
                    this.todoList = [
                        ...this.todoList,
                        newTodo,
                    ]
                })
                .catch((error) => {
                    this.todoCreationError = error;
                });
        }
    },
    created() {
        this.loadTodos();
    },
}
</script>

Great, we have a working component. The client is happy since he can try the application even though it is a work in progress. Now that we know that his expectation are met, it is time to meet ours.

Listing the pros and cons of the component can be useful in this case. It will allow us to have a complete picture of the state of the component and we will be able to prioritize the tasks to be done.

On the bright side, the component works. He has every needed features and we managed to build it relatively fast. On the other hand, we have a lot to improve before shipping it:

It has too many responsibilities (data fetching, business rules applying to the data, actions to add and modify data, the display of all of those information);
Nothing here is reusable;
It seems hard to maintain, at least it is hard to read through (a hundred lines, without the task achievement logic).

Let us iterate a few times until we are happy about the result!

Before Vue 3, a first step toward clean components

This is kind of a bonus section where we will refactor the component using present tools. You can skip it if you are only interested in the Composition API or if you are not familiar with the advanced concept of scoped slots. On the other hand, I do think that it is an interesting pattern to see if not to learn and use.

I had the chance to work with a friend and former colleague, Edouard Cattez, on a project for a big French retailer. The Front-End of this project was made, you guessed it, using Vue.js.

We had an issue with the code base that we could not name. For several months we worked hard on it, but could not figure what it was that make so difficult to add or modify features.

This was about the same time where I started to really dive into the concepts of Clean Code, Clean Architecture and Software Craftsmanship.

One day, when talking to that friend, we finally were able to find the underlying issue, our code base lacked separation of concerns.

Every components in our application started to get quite big since they managed their template, data managing and styles. This way of writing components can work fine, as long as it does not get out of hands.

Our components, however, managed a lot of business logic and associated templates. It causes a great amount of cognitive load to read through since the components held the intent and the implementation of the business logic.

We needed a way to separate the concerns, to have the business logic in one place and the templates in another. We could drop the Single File Components or even write mixins, but those solutions sounded wrong in our context.

The issue was not that the template and the data managing were in the same file. It had more to do with the fact that we mixed the intent and the implementation. Like an application without interfaces, only implementations.

This is were we found out about the great article and pattern from Adam Wathan, Renderless Components in Vue.js.

I will not dig too deep inside the matter since his article already explain it all. Just know that it works by creating a renderless component, responsible for the data managing. This renderless component then provides information for the "view component" to use thanks to scoped slots.

How could we apply this pattern in our TODO-list? Let us first try to extract the logic inside a renderless component, named TodoListManager:

<!-- No template tag, we will use a render function -->
<script>
export default {
    name: 'todo-list-manager',
    data() {
        return {
            loadingError: '',
            todoList: [ ],
            todoCreationError: '',
        };
    },
    computed: {
        doneCount() {
            return this.todoList.filter(todo => todo.done).length;
        },
        totalCount() {
            return this.todoList.length;
        },
    },
    methods: {
        loadTodos() {
            this.loadingError = '';
            fetch(import.meta.env.VITE_TODOS_URL)
                .then((response) => {
                    if (!response.ok) {
                        throw new Error('An error has occurred while loading todos');
                    }
                    return response.json();
                })
                .then((todos) => {
                    this.todoList = todos;
                })
                .catch((error) => {
                    this.loadingError = error;
                });
        },
        achieveATodo(id) {
            // [...] Call the API to achieve the task
        },
        addTodo(content) {
            this.todoCreationError = '';
            fetch(import.meta.env.VITE_TODOS_URL, {
                method: 'post',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ content })
            })
                .then((response) => {
                    if (!response.ok) {
                        throw new Error('An error has occurred while creating todo');
                    }
                    return response.json();
                })
                .then((newTodo) => {
                    this.todoList = [
                        ...this.todoList,
                        newTodo,
                    ]
                })
                .catch((error) => {
                    this.todoCreationError = error;
                });
        }
    },
    created() {
        this.loadTodos();
    },
    render() {
        // Only display the content inside of the default slot, with every needed information
        return this.$slots && this.$slots.default && this.$slots.default({
            loadTodos: this.loadTodos,
            loadingError: this.loadingError,
            todoList: this.todoList,
            doneCount: this.doneCount,
            totalCount: this.totalCount,
            achieveATodo: this.achieveATodo,
            addTodo: this.addTodo,
            todoCreationError: this.todoCreationError,
        });
    },
}
</script>

While the view component could be like this one:

<template>
    <!-- Use our renderless component -->
    <!-- You can see that not only data are provided but also methods, computed, etc -->
    <todo-list-manager v-slot="{
        loadTodos,
        loadingError,
        todoList,
        doneCount,
        totalCount,
        achieveATodo,
        addTodo,
        todoCreationError,
    }">
        <!-- Here, we can use every reactive information provided by the renderless component -->
        <h1>My TODO list! ({{ doneCount }} / {{ totalCount }})</h1>

        <!-- Error management -->
        <p v-if="loadingError">
            {{ loadingError }}
            <button @click="loadTodos">Reload</button>
        </p>

        <ul v-else>
            <li v-for="todo in todoList" :key="todo.id">
                {{ todo.content }}
                <button @click="achieveATodo(todo.id)">Validate</button>
            </li>
        </ul>
        <form @submit.prevent="() => addTodo(newTodoContent)">
            <label>
                What do you have to do?
                <!-- newTodoContent may come from the view component or the renderless one -->
                <input v-model="newTodoContent">
            </label>
            <input type="submit" value="Create">
            <!-- Error management -->
            <p v-if="todoCreationError">{{ todoCreationError }}</p>
        </form>
    </todo-list-manager>
</template>

<script>
// [...]
</script>

We could go even further by extracting the API call inside a JS module, creating a generic loading and error display management component, etc. Those enhancements are out of the scope of the article, but still great to do. What we can do now, however, is to keep iterating on the renderless component.

Our TodoListManager seems greatly filled to me. What if we only need to list the tasks? What if we only need to create a new one?

We could ignore the data exposed by the renderless component that we do not need. However, I find it more clear to explicitly use the renderless component responsible for the creation of a task and / or the one responsible for the listing. Here is how we can achieve that.

First, the creation logic is extracted in a new renderless component, TodoCreationManager:

<script>
export default {
    name: 'todo-creation-manager',
    data() {
        return {
            todoCreationError: '',
        };
    },
    emits: [ 'todo-created' ],
    methods: {
        addTodo(content) {
            this.todoCreationError = '';
            fetch(import.meta.env.VITE_TODOS_URL, {
                method: 'post',
                headers: {
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ content })
            })
                .then((response) => {
                    if (!response.ok) {
                        throw new Error('An error has occurred while creating todo');
                    }
                    return response.json();
                })
                .then((newTodo) => {
                    // We don't have any reference to the list here
                    // We can, however, send an event with the created task
                    this.$emit('todo-created', newTodo)
                })
                .catch((error) => {
                    this.todoCreationError = error;
                });
        }
    },
    render() {
        return this.$slots && this.$slots.default && this.$slots.default({
            addTodo: this.addTodo,
            todoCreationError: this.todoCreationError,
        });
    },
}
</script>

Our TodoListManager component is now only responsible for the fetching of the tasks list.

Then, in our view component, we need to nest the two renderless component and use the logic from them both in the template:

<template>
    <!-- Use our renderless component -->
    <!-- You can see that not only data are provided but also methods, computed, etc -->
    <todo-list-manager v-slot="{
        loadTodos,
        loadingError,
        todoList,
        doneCount,
        totalCount,
        achieveATodo,
        todoCreated,
    }">
        <!-- A second renderless component, managing the creation of a task -->
        <!-- 
            When this component notify us that a new task is created,
            we can add it directly to the list by calling a method
            on the todo-list-manager renderless component
         -->
        <todo-creation-manager
            v-slot="{
                addTodo,
                todoCreationError,
            }"
            @todo-created="todoCreated"
        >
            <!-- Here, we can use every reactive information provided by the renderless component -->
            <h1>My TODO list! ({{ doneCount }} / {{ totalCount }})</h1>

            <!-- Error management -->
            <p v-if="loadingError">
                {{ loadingError }}
                <button @click="loadTodos">Reload</button>
            </p>

            <ul v-else>
                <li v-for="todo in todoList" :key="todo.id">
                    {{ todo.content }}
                    <button @click="achieveATodo(todo.id)">Validate</button>
                </li>
            </ul>
            <form @submit.prevent="() => addTodo(newTodoContent)">
                <label>
                    What do you have to do?
                    <!-- newTodoContent may come from the view component or the renderless one -->
                    <input v-model="newTodoContent">
                </label>
                <input type="submit" value="Create">
                <!-- Error management -->
                <p v-if="todoCreationError">{{ todoCreationError }}</p>
            </form>
        </todo-creation-manager>
    </todo-list-manager>
</template>

It is a pattern that I adopted for every component with complex business logic. It helps keeping your view component clean and concise. However, since it is based on a renderless component, it adds one to the components tree each time you use it. It is also worth noting that it is an advance pattern that adds to the entry cost of your code base.

How is this elegant solution compared to the new Composition API? Let us find out.

Refactoring in Vue 3 with the Composition API

In this section, I will assume that you are already familiar with the intent and the basic syntax of the Composition API.

I made an article introducing the API in case you never heard about it. Please read it first if you are afraid of being confused by the syntax.

We have two implemented features:

Fetch the todo list;
Add a new one.

You can try to follow the same pattern while implementing the task achievement if you want.

Let us start with the list fetching. First, we will create a new ES module with a method that contains every pieces of information about the todo list. It is basically the same as the data inside the carryall component, but with a different syntax:

import { ref, computed } from 'vue';

export const useTodoList = () => {
    // First, we create the reactive data and computed
    const todoList = ref([ ]);
    const doneCount = computed(() => {
        return todoList.value.filter(todo => todo.done).length;
    });
    const totalCount = computed(() => {
        return todoList.value.length;
    });

    const loadingError = ref('');

    // Then we create the method that will manipulate those data
    const loadTodos = () => {
        loadingError.value = '';
        fetch(import.meta.env.VITE_TODOS_URL)
            .then((response) => {
                if (!response.ok) {
                    throw new Error('An error has occurred while loading todos');
                }
                return response.json();
            })
            .then((todos) => {
                todoList.value = todos;
            })
            .catch((error) => {
                loadingError.value = error;
            });
    }

    const achieveATodo = (id) => {
        // [...] Call the API to achieve the task
        // Move it in a new method useTodoAchiever
    };

    // This method will be useful soon
    const todoCreated = (newTodo) => {
        todoList.value = [
            ...todoList.value,
            newTodo
        ]
    }

    // Finaly, we return the information that could be useful for our clients
    return {
        todoList,
        doneCount,
        totalCount,
        loadingError,
        loadTodos,
        achieveATodo,
        todoCreated,
    }
}

These information will be consumed by our view component's setup method. Here is the TodoList:

<template>
    <!-- The template remains untouched -->
</template>

<script>
import { useTodoList } from './index.js';

export default {
    name: 'todo-list',
    setup() {
        // You cannot destructure the returned value here or you will loose Vue's reactivity
        const todoListData = useTodoList();

        todoListData.loadTodos();

        return {
            todoList: todoListData.todoList,
            doneCount: todoListData.doneCount,
            totalCount: todoListData.totalCount,
            loadingError: todoListData.loadingError,
            loadTodos: todoListData.loadTodos,
            achieveATodo: todoListData.achieveATodo,
        }
    },
}
</script>

We can now do the same with the task creation process:

export const useTodoCreation = ({
    // Method called when a todo is created
    onTodoCreated = () => {},
}) => {
    // Create the reactive data
    const todoCreationError = ref('');

    // The method used to create a new task
    const addTodo = (content) => {
        todoCreationError.value = '';
        fetch(import.meta.env.VITE_TODOS_URL, {
            method: 'post',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ content })
        })
            .then((response) => {
                if (!response.ok) {
                    throw new Error('An error has occurred while creating todo');
                }
                return response.json();
            })
            .then(onTodoCreated)
            .catch((error) => {
                todoCreationError.value = error;
            });
    }

    // Return the needed information
    return {
        todoCreationError,
        addTodo,
    }
}

Plug what is needed inside the view component:

<script>
import { ref } from 'vue';
import { useTodoList, useTodoCreation } from './index.js';

export default {
    name: 'todo-list',
    setup() {
        // You cannot destructure the returned value here or you will loose Vue's reactivity
        const todoListData = useTodoList();
        const todoCreationData = useTodoCreation({
            // Plug the method that will update the list when a task is created
            onTodoCreated: todoListData.todoCreated,
        });
        const newTodoContent = ref('');

        todoListData.loadTodos();

        return {
            todoList: todoListData.todoList,
            doneCount: todoListData.doneCount,
            totalCount: todoListData.totalCount,
            loadingError: todoListData.loadingError,
            loadTodos: todoListData.loadTodos,
            achieveATodo: todoListData.achieveATodo,
            todoCreationError: todoCreationData.todoCreationError,
            addTodo: todoCreationData.addTodo,
            newTodoContent,
        }
    },
}
</script>

The last thing we can do is to create reusable component for the display of a task and for the creation form.

<!-- TodoCreation.vue -->
<template>
    <form @submit.prevent="() => addTodo(newTodoContent)">
        <label>
            What do you have to do?
            <input v-model="newTodoContent">
        </label>
        <input type="submit" value="Create">
        <!-- Error management -->
        <p v-if="creationError">{{ creationError }}</p>
    </form>
</template>

<script>
export default {
    name: 'todo-creation',
    // Declare what events will our component emit
    emits: [
        'create-todo',
    ],
    props: {
        creationError: String,
    },
    data() {
        return {
            newTodoContent: '',
        }
    },
    methods: {
        addTodo(content) {
            this.$emit('create-todo', { content });
        }
    },
}
</script>

<!-- TodoDisplay.vue -->
<template>
    {{ content }}
    <button @click="achieveTodo()">Validate</button>
</template>

<script>
export default {
    name: 'todo-display',
    emits: [
        'achieve-todo',
    ],
    props: {
        content: String,
    },
    methods: {
        achieveTodo() {
            this.$emit('achieve-todo');
        }
    },
}
</script>

<!-- TodoList.vue -->
<template>
    <!-- Here, we can use every reactive information provided by the renderless component -->
    <h1>My TODO list! ({{ doneCount }} / {{ totalCount }})</h1>

    <!-- Error management -->
    <p v-if="loadingError">
        {{ loadingError }}
        <button @click="loadTodos">Reload</button>
    </p>

    <ul v-else>
        <li v-for="todo in todoList" :key="todo.id">
            <todo-display
                :content="todo.content"
                @achieve-todo="() => achieveATodo(todo.id)"
            ></todo-display>
        </li>
    </ul>
    <todo-creation
        :creation-error="todoCreationError"
        @create-todo="addTodo"
    ></todo-creation>
</template>

<script>
    // [...]
</script>

This is even cleaner than the solution using renderless component to me since it does not add components to the tree. The Composition API allows for a strict segregation of concerns. Our components can use business logic without knowing implementation details.

It will, however and just like the renderless components, adds to the entry cost of our projects. That is why I will use it pragmatically and try to make it the most readable possible for newcomers. For instance, in this application, I only used it in the TodoList component.

On the next episode...

I hope that this series helps you better understand the benefits of Vue 3's Composition API! Please send feedback of your journey learning to use this new toy :)

What do you think about those two methods? Which one is the clearer, the one that you will start to use?

Next on the series, I will show you how to get rid of Vuex thanks to the Composition API.

Vue 3's Composition API and the segregation of concerns

Thomas Ferro — Sun, 23 Aug 2020 17:51:42 +0000

A novelty worth digging

I always think that it is best to put things in context. That is why I wrote a first article about my take on the state of Vue before the 3.0, which is currently available as a release candidate.

However, the main subject of this series is one of Vue 3's new feature: the Composition API. It is the one that I anticipate the most and it is finally time we discuss it!

Shiny new toys

This article should be the shortest of the series, since the subject has already been discussed many times by people way more interesting and smart than I am.

The Composition API was created to answer two common issues that occur when your Vue application starts to get big.

Code organization

Have you ever had to maintain really big components, with complex logic implying a lot of data, computed, methods, etc? When trying to read those types of components, the main issue is to keep track of what everything is doing and how do they interact with each other. With the current Options API, you have to navigate back and forth inside the Vue instance, which causes a great cognitive load.

Vue 3 tries to resolve this issue by adding a new method to the Vue instance, the setup. This method can be seen as the component's entry point, being called before the beforeCreated hook and receiving the props as an argument. The returned value is an object containing every available information for the template to use.

This is the place where you will write all of your component logic, no matter if we are talking about data, computed, watcher, etc.

There is still a missing piece to this puzzle, how do we write data, computed, watcher, methods and more in that new setup method?

Vue 3 provides a new tool to create those reactive data and more: the Reactivity API.

It may not be relevant for now, but here is a small example of how to create a reactive data using the Reactivity API:

import { ref } from 'vue';

const count = ref(0);

// Accessing ref's value in JS
console.log('Count:', count.value)

// Modifying the value
count.value += 1

As you can see, you have to explicitly access the ref's value when manipulating it in JS. It bugs me a little, but you won't have to do so in the template and can directly access the value, as we will see later.

Please take a look at the Reactivity API's reference for more information about what is contained in it.

Ok, but how do those two APIs fit together? Let us see that with an example. First, we will write it using the Options API, then we will do it à la Vue 3.

Let us say that we have a component managing the loading and display of blog posts, a minimalist version of it could be like this:

export default {
    name: 'blog-posts',
    data() {
        return {
            posts: [],
            loadingStatus: '',
            error: '',
        };
    },
    computed: {
        blogPostsLoading() {
            return this.loadingStatus === 'loading';
        },
        blogPostsLoadingError() {
            return this.loadingStatus === 'error';
        },
    },
    methods: {
        loadBlogPosts() {
            this.loadingStatus = 'loading';
            fetch(process.env.VUE_APP_POSTS_URL)
                .then((response) => {
                    if (!response.ok) {
                        throw new Error(response.status);
                    }
                    return reponse.json();
                })
                .then((posts) => {
                    this.posts = posts;
                    this.loadingStatus = 'loaded';
                })
                .catch((error) => {
                    this.error = error;
                    this.loadingStatus = 'error';
                });
        },
    },
    created() {
        this.loadBlogPosts();
    },
}

Using the new provided tools, we can put all of the logic in the setup:

import { ref, computed } from 'vue';

export default {
    name: 'blog-posts',
    setup() {
        const loadingStatus = ref('');
        const error = ref('');
        const posts = ref([]);

        const blogPostsLoading = computed(() => {
            return loadingStatus.value === 'loading';
        });
        const blogPostsLoadingError = computed(() => {
            return loadingStatus.value === 'error';
        });

        const loadBlogPosts = () => {
            loadingStatus.value = 'loading';
            fetch(process.env.VUE_APP_POSTS_URL)
                .then((response) => {
                    if (!response.ok) {
                        throw new Error(response.status);
                    }
                    return reponse.json();
                })
                .then((fetchedPosts) => {
                    posts.value = fetchedPosts;
                    loadingStatus.value = 'loaded';
                })
                .catch((apiError) => {
                    error.value = apiError;
                    loadingStatus.value = 'error';
                });
        };

        // Return every information to be use by the template
        return {
            loadingStatus,
            // You can rename those information if needed
            loadingError: error,
            loadBlogPosts,
            blogPostsLoading,
            blogPostsLoadingError,
        };
    },
};

It can seem not so useful in a component with few logic, but it already helps developers keep track of the different pieces without scrolling between the Vue instance's options. We will see later in this article and the next ones how to leverage the most out of it.

We can also extract the logic by creating an ES module (posts.js) managing the data and exposing the useful information:

import { ref, computed } from 'vue';

export const useBlogPosts = () => {
    const loadingStatus = ref('');
    const error = ref('');
    const posts = ref([]);

    const blogPostsLoading = computed(() => {
        return loadingStatus.value === 'loading';
    });
    const blogPostsLoadingError = computed(() => {
        return loadingStatus.value === 'error';
    });

    const loadBlogPosts = () => {
        loadingStatus.value = 'loading';
        fetch(process.env.VUE_APP_POSTS_URL)
            .then((response) => {
                if (!response.ok) {
                    throw new Error(response.status);
                }
                return reponse.json();
            })
            .then((fetchedPosts) => {
                posts.value = fetchedPosts;
                loadingStatus.value = 'loaded';
            })
            .catch((apiError) => {
                error.value = apiError;
                loadingStatus.value = 'error';
            });
    };

    // Return every information to be use by the consumer (here, the template) 
    return {
        loadingStatus,
        // You can rename those information if needed
        loadingError: error,
        loadBlogPosts,
        blogPostsLoading,
        blogPostsLoadingError,
    };
}

Our component will then only manage the template based on data provided by the module. Complete separation of concerns:

import { useBlogPosts } from './posts.js';

export default {
    name: 'blog-posts',
    setup() {
        const blogPostsInformation = useBlogPosts();
        return {
            loadingStatus: blogPostsInformation.loadingStatus,
            loadingError: blogPostsInformation.loadingError,
            loadBlogPosts: blogPostsInformation.loadBlogPosts,
            blogPostsLoading: blogPostsInformation.blogPostsLoading,
            blogPostsLoadingError: blogPostsInformation.blogPostsLoadingError,
        };
    },
};

Again, it helps clarify your code and decouple the intent from the implementation, which is always nice.

You may already have thought about it, but this way of creating modules can help us reuse logic!

Logic reuse

We already have some tools that help us create logic to be used by many components. Mixins, for instance, let write you any Vue instance's options to be injected in one or many components.

These approaches share one downside, they lack clarity.

You never clearly know which mixin imported which option unless you read through all of them. It can easily become a nightmare for developers trying to understand how the components work, having to navigate through the Vue instance and the globally and locally injected mixins. Moreover, mixins' options can collide with each others, leading to a knot bag, not to say a mess.

With the Composition API, any component can pick what he needs from different modules. Clearly stated in the setup method, the developers can see what was taken from where and even rename variable if it helps understand the intent better.

I think that clarity is a, if not the, most important concern when writing applications to be actively maintain for years. The Composition API gives us the tool to do so in an elegant and practical way.

Wait, there is more?

The two main goals look pretty achieved to me, but the Composition API should not be reduced to those two concerns.

It will also benefit the testability of our applications, let me explain how.

Before Vue 3 we had to instantiate the component, inject mocked dependencies if needed, and only then start hacking around assertions. This way of testing can lead to tests suites strongly coupled to the actual implementation. The kind of tests that age poorly and can do way more harm than good.

Now we can create ES modules encapsulating the domain logic and exporting the data and methods to be used. Those modules will be written in almost-pure Javascript since they will still use Vue's API, but not in the context of a component.

Our tests can simply consume the exported information, just like our components will!

The art of teaching

You may have noticed by the fact that I am writing a whole series about it, I am really excited about this new API. It scratches itches that I've had for a long time, trying to apply clean code principles into my front-end applications. I think it will help us tremendously increase the quality of our components and applications if well used.

However, the Composition API is an advanced concept. I do not think that it should replace the actual way of writing components. Moreover, we will still encounter legacy code written before Vue 3, so our previous knowledge is still useful.

I already discuss this issue in the previous article, but it is really important to keep this in mind: not everyone is lucky enough to discover the 3.0 after two years of practicing Vue almost daily.

Some people will start using Vue with the 3.0, and a whole new API like this one adds a lot to the already big entry cost. A newcomer now have to understand it in addition to the "classical" Options API.

How do you think that the new API should be introduced to newcomers? I personally think that it should be just like Vuex or Vue Router, introduced later as an advanced tool. It should be added on top of a solid foundations of knowledge and used practically.

Once again, share your thoughts!

What do you think about the new Composition API?

Are you ready to use it as soon as the 3.0 is released?

Please let everyone know and let us discuss all that :)

Now that the subject is theoretically introduced, what is next? I will get my hands dirty and try the make the most out of the Composition API, starting in the next article with a refactoring session!

The state of Vue - Will the 3.0 still be approachable?

Thomas Ferro — Tue, 18 Aug 2020 11:11:06 +0000

Easy to get started with, but how hard to master?

It should not be long before we get our hands on Vue.js next major release! I cannot wait - and actually have not waited - to try the new features to build faster and cleaner applications thanks to the great work of Evan You and the community.

However, the pasts months had me wonder about the global reception of those new features, especially the Composition API. I sure am excited and ready to use it, but is everyone on the same page?

Let me try to explain why I am concerned about the future of the framework if it continues down that path.

Approachable... at first

I remember more than four years ago, when I joined my first company and heard about Vue for the first time. Having tried only Angular.js in my years of study, I was anxious, not knowing if I could learn a completely new approach relatively fast.

Fast forward a few days later, I felt like I was up and running! The entry cost coming from Angular.js appeared quite cheap. Everything seemed easier, more obvious.

When I say up and running, I did not mean that I knew every part of the framework and the ecosystem. I knew enough, however, to start contributing on the company's projects. The learning phase never stopped, as you may imagine. Every new feature to implement or bug to fix was an opportunity to teach myself good components and applications building practices.

Digration about training

For now more than a year, I have been lucky enough to train people into Vue.js. The main target are developers already having a solid experience in Javascript so that we can focus on the framework. My goal is to provide them with the keys to build professional applications using this specific tool.

I was confident enough in my technical skills and knowledge, but not in my teaching skills. How to build a compelling and complete training? One that supports students up to a sufficient level of mastery?

With the help of a soft-skills coach and the support of my technical director, a first draft of the training was ready to be tested on the field.

Not long after, I was teaching Vue.js based on that first draft and I had a feeling that something was off. I gave the maximum amount of keys - knowledge about what the framework can do and how - and it seemed to connect with them. However, when asked to build a feature with no technical details, like in our day to day conversation with product owners and business experts, few where the ones who could provide a working solution.

What is it that makes Vue.js so hard to condensed in three days? Condensed... It may be it. Instead of condensing every feature into the training and risking to overwhelm people with non-essential information, why not distill those information through real world examples?

That is what I tried to apply in the latest version of the training, and it seems to work for most people. Of course, everyone has is own way of learning and there is no silver bullet, but I am convinced that it is a better way of teaching.

This training experience and the discovery of another framework, Svelte, had me wonder about my issues with Vue.js. It is certainly approachable at first, but what it is that confused me when learning Vue and seems to confuse those who want to get started?

A hundred ways to achieve the same goal

Vue.js provides different ways to define props that your component accepts. For instance, here are three valid ways to tell that your component can receive an array of students:

// 1. The simpliest solution, without any check

{
  props: [ 'students' ],
}

// 2. Type checked props

{
  props: {
    students: Array,
  },
};

// 3. Type checked props with fallback

{
  props: {
    students: {
      type: Array,
      // Another itch, the default value needs to be
      // inside a method for arrays and objects
      default() { return []; },
    },
  },
};

You have the same behaviour with the definition of computed properties and watchers.

This expandable API allows you to write less code if you do not need the extra options, which is nice... when you already know all the syntaxes.

When learning Vue, however, it tends to add a significant amount to the already big cognitive load.

As you may imagine, this is not going to get any better with the addition of the whole new Composition API. Newcomers will now be exposed with a whole new way or writing components logic plus the classical Options API.

I know that there is no silver bullet, that we have to choose between providing shorthands for developers or force everyone to use the expanded, more verbose version. I still think, however, that the following questions deserve to be asked:

Do we really need all of those options? Where do the convenience end and the pragmatism begin?

Reactivity and references caveats in the hands on the developer

You may have seen that the Vue instance's data is often described as a function returning the actual data. Do you know why? According to the documentation, you must do that so "[...]each instance can maintain an independent copy of the returned data object".

It sure sounds to me like a Javascript issue invading the framework's API, but I can get it. The thing that bugs me is that you can describe the data directly as an object to if you won't reuse the component.

Two syntaxes because of a references issue, bummer.

Going into the reactivity field, have you ever wonder why linters and compilers tend to get mad at you for not adding a key attribute when using the v-for directive? It is "to maintain predictable behavior, such as object constancy in animations." Again, I cannot help but think that this is not something we should manage as users.

I get that it could add complexity into the framework. Yet, I found it better to have technical complexities managed in the framework and leave the applications as clear as possible from them.

The same goes with the deep option in watchers, which allows you to not only watch the changes in the reference to an array or an object but also the changes in the array's elements or the object's properties. This last one, however, can be discussed since it can be useful to only listen to changes in the variable's reference.

Shouldn't those concerns be managed by the framework by default? Are we not using a framework to ignore those concerns in the first place? Should the developer know about implementation details in order to use a framework or library?

Share your thoughts and opinion!

I know that I am just exposing points without bringing anything to the table. The goal is only to provide a context that we can use to build a constructive debate. I will dive deeper into my thoughts in the last article of this series.

What are your thoughts on the subject?

How did you first learn the basics of Vue.js?

Have you felt overwhelmed at first by the API's options?

Are you concerned about the addition of more APIs?

I will be glad to hear from you about it. On the next articles, we will actually discuss about Vue 3's Composition API and try to make the most out of it!

Welcome.. To Deno Park!

Thomas Ferro — Thu, 23 Jul 2020 10:17:12 +0000

Tired of hacking Node applications? Introducing Deno

What? Why? How?

My rule of thumb for effective technology watch is the following: don't loose your time on shiny new things.

Wait for the hype to pass and see if the opinions are still mostly positive after that, once the emotions and feelings are out of the way. With the release of the 1.0, I think that it is time to really dig into Deno!

First thing first, what problem does Deno solve? Mostly the same as Node.js. From building CLI's and HTTP API to creating developers' tools.

I have been working with Node.js for more than two years now, and it was far from a cliché love story between us.

There are aspects of this runtime that I like. It is especially a great tool for front-end developers wanting to do some back-end work.

The heavy setup needed to test your code or use a superset of Javascript, I'm not so found of.

You can guess that my curiosity was piqued when I first eared of Deno, and here are the reasons why I was interested in learning it:

Dependencies hell

Deno dependencies management is quite different from Node.js. It works with a cache on your computer where the third party modules will be stored.

Using a dependency does not require you to install it with a command, but just reference it in an import. Just like importing a module from another local file:

import { serve } from "https://deno.land/std/http/server.ts";

Like the documentation explains it and how we will see in the next sections, importing from urls can seem messy and inconsistency prone. Some patterns are already used to manage your dependencies' locations in a unique place.

Assuring the consistency of the dependencies between your development environment and the production is also a huge deal. To do so, you can generate a lock file that will be used to validate the cache integrity. Another good practice is to reference a specific version number:

import { copy } from "https://deno.land/std@0.50.0/fs/copy.ts";

Instead of:

import { copy } from "https://deno.land/std/fs/copy.ts";

Secure by design

Have you ever wonder what could happen if one of the dependencies of your Node.js application's dependencies did something malicious? Sending personal data to who knows where? Reading through your files? I never heard such stories, but it worth considering, better safe than sorry!

Deno is secure by default, which means that your application is not allowed to do things like reading through your file system without explicit authorization when running the code. Here is what happens if you try to run an application without the requested permissions:

deno run index.ts --http
Serving the HTTP API on port 8000
error: Uncaught PermissionDenied: network access to "0.0.0.0:8000", run again with the --allow-net flag
    at unwrapResponse ($deno$/ops/dispatch_json.ts:43:11)
    at Object.sendSync ($deno$/ops/dispatch_json.ts:72:10)
    at Object.listen ($deno$/ops/net.ts:51:10)
    at Object.listen ($deno$/net.ts:155:22)

Types and tests

I have never been a Typescript aficionados, but I admit that it helps you build a safer code base, thanks to the statically typed transcompiler. If you are not allergic either: rejoice! Deno supports Typescript out of the box.

I am, however, a test aficionados and I admit that it helps you build a safer code base, thanks to the safeguard that it provides. If you are not allergic either: rejoice! Deno supports testing out of the box. You will need to write your test using Deno.test and if needed using the assertions library.

// Spoiler alert!!
Deno.test("Initial park with two dinosaurs", () => {
  const initialPark = initiatePark();

  assertEquals(initialPark?.dinosaurs?.length, 2);
});

Building a Jurassic park manager

Welcome... to Deno Park!

I am sure that there are a lot of articles and tutorials about the making of "Hello World"s and "TODO list"s out there. This is fine if you want to get started, but it is not enough for me to make my own opinion about a tool. You can also find basic examples in the documentation.

What I want to build to try Deno is something that feels more complete. A project that may not be useful on his own, but who is fun to build and who can show me the strengths and limitations behind the hype.

This project is Deno Park, defenitly not a rip off. You will be able to manage your dinosaurs: breeding, feeding and euthanize them if necesarry. Those actions will be available via a CLI and a HTTP API.

Building this project will highlight several common themes of "real world applications", such as writing well tested domain code and building APIs on top of it. The only important part missing is a database connection.

You can find the final product on Github if you are interested.

Setting up

According to a survey that I just made up, 92% of all side projects follow this pattern:

Write down ideas about the project;
Spend two days setting it up;
Get bored / find something similar on Github / realize that there is little to no added value;
Archive and never touch it again.

I don't say that Deno will make you finish project. It won't. But it comes with enough tooling and compatibility options to reduce the setup. Hooray, right?

So, what do we need to start a Deno project? A package.json file with the dependencies and a description? Dozens of tools, plugins and configuration files? Not exactly. Not at all.

First, we will download and install Deno. I will let you do that following the getting started guide.

Then create a new folder... And we are ready! (We previously saw that a lock file can be used for dependency management, but let us keep this simple for now)

One thing that I really enjoyed while trying Deno is the tooling that comes out of the box. Remember when you needed to spend half a day on tools configuration? Now you only need to spend some time on the documentation!

You want to run all of your tests? deno test .

Run the project locally? deno run index.ts (if no permission is needed)

Format your code base? deno fmt

Bundle your application and his dependencies into a single js file? deno bundle index.ts deno-park.js

And you can count on the community to create tools for more advanced need like hot reloading.

Ok! Great! I hear you say, Little to no setup! But what about actual code?? Actual code? Silly you, I will show you something far more valuable than code: tests!

Red, green, refactor: a mantra for a healthy domain code

This is not an article about Test Driven Development - or TDD - so I won't be long on the subject. Just know that it is a set of principles and practices that helps you build better software.

The main principle is to write the application starting with a failing test, then a naive implementation, and finally do the necessary refactoring while keeping the tests suites passing.

Following TDD principles with Deno feels as smooth and good as it does with Go. Thanks to the tooling provided out of the box, you can write the test with no additional library to install and setup.

I started this project by listing the features that I wanted:

Being able to create a new park with two dinosaurs;
Being able to breed two dinosaurs, with the child being added to the park;
The dinosaurs loose "hunger points" over time, until starvation;
The manager can feed and euthanize dinosaurs.

What is the shortest feature to implement here? The initial park!

Deno.test("Initial park with two dinosaurs", () => {
  const initialPark = initiatePark();

  assertEquals(initialPark?.dinosaurs?.length, 2);
});

To answer this request, the minimal solution is to create the initiatePark method that returns a park with two dinosaurs. No need to implement anything else for now, the dinosaurs list can be an array of anything.

Then the second test comes in, with the need to breed dinosaurs:

Deno.test("Breed two dinosaurs", () => {
  let park = initiatePark();

  park = park.breed(0, 1, "Billy");

  assertEquals(park?.dinosaurs?.length, 3);
  assertEquals(park?.dinosaurs[2]?.name, "Billy");
});

We add a new breed method on the park, taking the dinosaurs to breed and the name of the child.

I choose to return the modified park instead of mutating the initial one. This is an implementation detail, but I like immutability.

Now comes the first edge case, what if the user tries to breed dinosaurs who do not exist? Let us create a test for that:

Deno.test("Cannot breed with a dinosaur not in the park", () => {
  const park = initiatePark();

  assertThrows(
    () => {
      park.breed(0, 12, "Billy");
    },
    CannotBreedDinosaursNotInPark,
  );

  assertThrows(
    () => {
      park.breed(12, 1, "Billy");
    },
    CannotBreedDinosaursNotInPark,
  );
});

And so on until we covered every feature!

Building a CLI and a HTTP API on top of the domain

We have seen that Deno can help us create solid domain code with its tools, but what about infrastructural code?

First, we can build a CLI on top of the domain code, managing the interactions with the user over the terminal.

To do so, Deno provides what I found to be an aesthetic and practical way to read through the standard input asynchronously:

import { readLines } from "https://deno.land/std@0.60.0/io/bufio.ts";
for await (const nextLine of readLines(Deno.stdin)) {
  // ...
}

You can display information to the user just like with Node.js, using the console object:

console.clear();
console.log("Welcome... to Deno Park!");

It also provides more tools in his standard libraries, but I let you read through them on your own!

Using many of those tools, you can build your own CLI! The one that I built may be a little bit complex to grasp at first so let's break down the most important parts.

The CLI presents to the user the information needed to manage the Park, such as the commands that can be used and the current state of the dinosaurs. This is done in the updateDisplay methods, called after every update:

const updateDisplay = (park: Park) => {
  console.clear();
  console.log("Welcome... to Deno Park!");
  if (park.gameOver) {
    console.log("You have no dinosaur left, game over!");
    return;
  }
  displayDinosaurs(park);
  displayCommands(commands);
};

Welcome... to Deno Park!
[0] 🙂 - 5
[1] 🙂 - 5
Type B to breed (eg: "B 0 1 Sam" to breed the first two dinosaurs and name the new one "Sam")
Type E to euthanize a dinosaur (eg: "E 1" to euthanize the dinosaur at index 1)
Type F to feed a dinosaur (eg: "F 2" to feed the dinosaur at index 2)

We also need to set an interval, passing the time on a regular basis and updating the display when it is done:

  setInterval(() => {
    park = park.passTime();
    updateDisplay(park);
  }, 6000);

The user can now enter his command, as shown in the examples. His input will be managed in a loop, checking if the command exists and executing it if so:

  for await (const command of readLines(Deno.stdin)) {
    let error = null;
    const commandHandler = getCommandHandler(commands, command);
    if (commandHandler) {
      try {
        park = commandHandler(park, command);
      } catch (e) {
        error = e.message;
      }
    }
    updateDisplay(park);
    if (error) {
      console.log("Error:", error);
    }
  }

Regarding HTTP API, I first tried to create one only with the standard libraries. You have to manage very low-level concerns and heavy lifting, but you can make it work.

A framework managing those complex and repetitive concerns can be used. In fact, you are probably using one when doing API with Node.js as well. I personally often use Express for these use cases.

The Deno ecosystem may be young, but we already have plenty of framework to use for building HTTP API. I tried oak since it has an API very similar to Express and a clear documentation. I am not going to explain how the framework works, you can refer to the documentation for that. However, here are the endpoints that I implemented:

export const initiateHttp = async (initialPark: Park) => {
  let park = initialPark;
  setInterval(() => {
    park = park.passTime();
  }, 6000);
  const router = new Router();

  router
    .get("/", (context) => {
      context.response.body = {
        ...park,
        gameOver: park.gameOver,
      };
    })
    .post("/feed", (context) => {
      try {
        park = park.feed(Number(helpers.getQuery(context)?.dinosaur));
      } catch (e) {
        context.response.status = 500;
        context.response.body = e.message;
      }
    })
    .post("/euthanize", (context) => {
      try {
        park = park.euthanize(Number(helpers.getQuery(context)?.dinosaur));
      } catch (e) {
        context.response.status = 500;
        context.response.body = e.message;
      }
    })
    .post("/breed", (context) => {
      const dinosaurs = helpers.getQuery(context)?.dinosaurs.split(",").map(
        Number,
      );
      const childName = helpers.getQuery(context)?.name;
      try {
        park = park.breed(dinosaurs[0], dinosaurs[1], childName);
      } catch (e) {
        context.response.status = 500;
        context.response.body = e.message;
      }
    });

  const app = new Application();
  app.use(router.routes());
  app.use(router.allowedMethods());

  const port = 8000;
  console.log("Serving the HTTP API on port", port);
  await app.listen({ port: 8000 });
};

As you may have noticed, the domain code is only used as an external source, which provide clear boundaries between concerns.

To production, and beyond!

Writing software is cool. Delivering it to the users is even cooler, if not mandatory!

Setting up a basic continuous integration workflow using Github Actions can help us get automatic feedback on every commit. It will ensure that our project is in a stable state and that we can put it in production - more - safely.

There seems to be no official Docker image, so I used the following: hayd/alpine-deno.

The workflow is two steps long, running the deno test command after checking out the code:

name: CI

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: hayd/alpine-deno:1.1.3

    steps:
    - uses: actions/checkout@v2

    - name: Run the tests
      run: deno test .

You can put your application in production using this Docker image too, I recommend that you take a look at LogRocket's article on the subject.

Wrapping up

I think you could tell, I really enjoyed trying Deno. All of what use to overwhelm me when doing Node.js projects is gone, and I can focus on what matters most: building application.

I am confident enough in it to make it a candidate for future professional pieces of software when the opportunity will come.

I am now eager to see if it will have the same popular success than Node.js, and to see if it keeps his promises with bigger, more complex projects in production!

DDD in action: Armadora - The board game

Thomas Ferro — Wed, 05 Feb 2020 11:27:05 +0000

Applying DDD tactical patterns to the making of a game.

How do you apply most of the DDD tools when you have no domain experts nor any team at all?

Since I want to train using those tools whenever possible, I decided to build what seems to be a good experience for me: adapting a board game.

The domain rules are simply the game's ones, and discussions with domain experts can be reduced to reading the guide!

However, I can only apply tactical patterns, which is a simplistic take on DDD. The discovery of the domain and the exchanges with domain experts are a critical component of DDD and ignoring it in a real project is nonsensical to me.

Anyway, let me introduce you to the game that I am building!

Game's rules

Here are the rules, based on the guide. The wording is important since it is already the Ubiquitous Language. No need to work with domain experts to build it in our case. Note that I will be only implementing the basic rules, not the advanced ones.

Armadora is a game where every player will try to get their hands on the most gold possible.

The game board is a 8x5 grid with two types of cell: the lands where the players will be able to put their warriors (more on that later) and the gold stacks with various quantity or gold.

The grid can be divided into territories by putting palisades between cells. A territory must be at least four squares wide.

At the beginning of a game, each player chooses a character (Orc, Goblin, Elf or Mage) and hide their warriors behind their screens.

Each player starts with the same army, depending on the number of players:

For two players, each one get 11 warriors of 1 point, 2 warriors of 2 points, 1 warrior of 3 points, 1 warrior of 4 points and 1 warrior of 5 points;
For three players, each one get 7 warriors of 1 point, 2 warriors of 2 points, 1 warrior of 3 points and 1 warrior of 4 points;
For four players, each one get 5 warriors of 1 point, 1 warrior of 2 points, 1 warrior of 3 points and 1 warrior of 4 points;

In the advanced rules set, the players also have power token based on their race and a reinforcement token.

Forty gold are then distributed randomly in eight piles: 1 pile of 3, 2 piles of 4, 2 piles of 5, 2 piles of 6 and 1 pile of 7.

When it is his turn, the player have to choose one of the following actions:

Put one of a remaining warrior tile on an empty cell, with the number hidden;
Put one or two palisades on the board, in an authorized border of a cell (one cannot put a palisade if it closes a territory of less than four cells);
Use the race's power (only in advanced rules);
Use reinforcement (only in advanced rules);
Pass his turn.

Once a player passed his turn, he cannot play anymore for the rest of the game.

The game ends once every player has passed they turn. Every armies' strength is revealed and the gold of each territory is given to the player with the greatest army.

In case of a tie, the players will compare their piles of gold, from highest to lowest.

Example: If the Elf have a pile of 6, a pile of 4 and a pile of 3 and the Orc have a pile of 6, one of 5 and one of 2, the Orc wins.

In a four-player game, the facing players can play as partners. We will not be implementing this feature in the first version.

Building the game

Now that the what is clear, we can focus on the how.

The game is implemented as a Go application, serving the information to the clients via an HTTP API and Web Sockets. These choices can and will be challenged later, but the first thing to focus on is the domain.

Every piece of code regarding the domain is written following the Test Driven Development principles. This way, I will be sure that every vital piece of the game is tested and functional.

The infrastructure matters are not tested at first, which I regret, but it was the most challenging part for me to do. Being a Go and especially a Web Sockets newbie, writing testable code for this part felt unnatural and I wanted to focus on delivering the value. However, as we will see in the last section, all of this layer will be re-written to be easily deployable.

On a brighter side, let us talk architecture. As the project is turn-based, it felt natural for me to build the game as an event driven system. We have a Game aggragate, on which domain events are applied to modify its state. We will see examples of events throughout the post. The main idea is to persist the way that lead to the current state of the system instead of the state itself.

The events, commands, aggregates and structures are based on the guide, which provides the ubiquitous language.

I choose not to apply CQRS patterns for now since there is no need to decorrelate the command and the query models. Again, this choice can be challenged.

Before diving into the game's implementation, let me first introduce the main concepts that we will see through the article.

Concepts

Domain events help us understand what happened in the system. They contain information about what happened via their type and their inner data.

I decided to create non-technical error events in order to keep a log of unwanted things happening. In practice, this means that an invalid move will produce a domain event.

The main part of the domain is the aggregate. There is only one here, the Game, on which domain events will be applied in order to modify his state.

Interactions with the domain and more specifically the aggregate are achieved using commands.

For instance, a player will make a move via a command. This command will receive the history of domain events for the game and a payload. If needed, an aggregate can be built using the history and decisions can be made using the game's state. In the end, the command will return the new domain events that occurred on the aggregate.

func SampleCommand(history []event.Event, commandPayload CommandPayload) []event.GameCreated {
    currentStateOfTheGame := game.ReplayHistory(history)
    // [...] Decisions based on the current state of the game.
    return []event.Event{
        event.AnEvent{
            // Payload
        },
        event.AnotherEvent{},
    }
}

Those concepts and more are also introduced in my feedback on the four days DDD training that I followed last year.

I will now briefly iterate through the different parts of the domain, explaining how I implemented them.

Initialization of a game

This first part will introduce many of the building blocks of the application, while implementing the setup of a game.

The initial command is the one used to create a game, the aptly named CreateGame. No big deal here, just a method that returns a GameCreated event.

func CreateGame() event.GameCreated {
    return event.GameCreated{}
}

We need a mechanism to be able to create a Game aggregate based on a history of events. Using a loop and a type switch, we will route the event to the right method on the aggregate.

func ReplayHistory(history []event.Event) Game {
    var returnedGame Game
    returnedGame = game{}
    for _, nextEvent := range history {
        switch typedEvent := nextEvent.(type) {
        case event.GameCreated:
            returnedGame = returnedGame.ApplyGameCreated(typedEvent)
        // [...] One case per managed event type
        }
    }
    return returnedGame
}

The ApplyGameCreated simply changes the game's state, making it waiting for players to join.

func (g game) ApplyGameCreated(event event.GameCreated) Game {
    g.state = WaitingForPlayers
    return g
}

Note that every Apply method return a new aggregate, to avoid side-effect.

Now that we have a game, we need to provide a way for players to join it. Another command will do the trick: JoinGame. This command, contrary to the previous one, needs a little bit of context provided by the payload.

type JoinGamePayload struct {
    Nickname  string
    Character character.Character
}

For the command to be fulfilled, the game needs to be in the right state, the game must not be already full and the character must not have been already taken:

func JoinGame(history []event.Event, joinGamePayload JoinGamePayload) []event.Event {
    gameToJoin := game.ReplayHistory(history)

    if gameToJoin.State() != game.WaitingForPlayers {
        return []event.Event{
            event.GameAlreadyStarted{},
        }
    }

    if len(gameToJoin.Players()) == 4 {
        return []event.Event{
            event.GameAlreadyFull{},
        }
    }

    for _, player := range gameToJoin.Players() {
        if player.Character() == joinGamePayload.Character {
            return []event.Event{
                event.CharacterAlreadyChosen{
                    Character: joinGamePayload.Character,
                },
            }
        }
    }

    return []event.Event{
        event.PlayerJoined{
            Nickname:  joinGamePayload.Nickname,
            Character: joinGamePayload.Character,
        },
    }
}

You have here examples of error events. I could have decided to implement them as returned error, but it felt more declarative this way. Another implementation choice that will certainly be challenged later.

Once two to four players joined the game, it can be started via the StartTheGame command.

The first thing to do is to check if there is enough players:

func StartTheGame(history []event.Event) []event.Event {
    newGame := game.ReplayHistory(history)

    if len(newGame.Players()) < 2 {
        return []event.Event{
            event.NotEnoughPlayers{
                NumberOfPlayers: len(newGame.Players()),
            },
        }
    }

    // [...]

When the game starts, the gold, palisades and warriors are distributed. How to represent that? With domain events!

The StartTheGame command can be completed with those events as following:

func StartTheGame(history []event.Event) []event.Event {
    newGame := game.ReplayHistory(history)

    if len(newGame.Players()) < 2 {
        return []event.Event{
            event.NotEnoughPlayers{
                NumberOfPlayers: len(newGame.Players()),
            },
        }
    }

    events := []event.Event{}

    warriorsToDistribute := warrior.WarriorsToDistribute(len(newGame.Players()))

    events = append(events, event.WarriorsDistributed{
        WarriorsDistributed: warriorsToDistribute,
    })

    goldStacksToDistribute := gold.GoldToDistribute()

    events = append(events, event.GoldStacksDistributed{
        GoldStacks: goldStacksToDistribute,
    })

    events = append(events, event.PalisadesDistributed{
        Count: 35,
    })

    return append(events, event.GameStarted{})
}

The WarriorsToDistribute and GoldToDistribute methods are extracted in another package for the sake of readability and because it is out of the command's responsibility.

Those events, when applied in the aggregate, put the game in the right state:

func (g game) ApplyGameStarted(event event.GameStarted) Game {
    g.state = Started
    return g
}

func (g game) ApplyWarriorsDistributed(event event.WarriorsDistributed) Game {
    players := []Player{}
    for _, player := range g.Players() {
        players = append(players, player.SetWarriors(event.WarriorsDistributed))
    }
    g.players = players
    return g
}

func (g game) ApplyGoldStacksDistributed(event event.GoldStacksDistributed) Game {
    g.board = board.NewBoard(event.GoldStacks)
    return g
}

func (g game) ApplyPalisadesDistributed(event event.PalisadesDistributed) Game {
    g.board = g.Board().SetPalisadesLeft(event.Count)
    return g
}

I made the player's SetWarriors and the board's SetPalisadesLeft methods to return a new instance that is why I reassign them to the game before returning it.

Now that the game is started, it is time for the players to actually play!

Anatomy of a turn

In standard rules, three actions are available: put a warrior on a land, put one or two palisades between cells or pass the turn.

Those three commands have two things in common. They can only be done by the current player, which is checked with the following assertion:

    currentGame := game.ReplayHistory(history)

    if currentGame.CurrentPlayer() != commandPayload.Player {
        return []event.Event{
            event.NotThePlayerTurn{
                PlayerWhoTriedToPlay: commandPayload.Player,
            },
        }
    }
    // [...]

They also all share the fact that the turn of the player ends after the command is handled. This is represented by the NextPlayer event.

Going to the more specific stuff, the PutWarrior command must check that the player have warrior of the requested strength left and that the cell is an empty land.

func PutWarrior(history []event.Event, payload PutWarriorPayload) []event.Event {
    currentGame := game.ReplayHistory(history)

    if currentGame.CurrentPlayer() != payload.Player {
        return []event.Event{
            event.NotThePlayerTurn{
                PlayerWhoTriedToPlay: payload.Player,
            },
        }
    }

    currentPlayer := currentGame.Players()[currentGame.CurrentPlayer()]

    if getWarriorsLeft(currentPlayer.Warriors(), payload.Warrior) == 0 {
        return []event.Event{
            event.NoMoreWarriorOfThisStrength{
                Strength: payload.Warrior,
            },
        }
    }

    if cellAlreadyTaken(currentGame.Board(), payload.Position) {
        return []event.Event{
            event.CellAlreadyTaken{
                Position: payload.Position,
            },
        }
    }

    return []event.Event{
        event.WarriorPut{
            Player:   payload.Player,
            Strength: payload.Warrior,
            Position: payload.Position,
        },
        event.NextPlayer{},
    }
}

The PutPalisades is more complex since it must check the grid's validity after putting the requested palisades. If putting the palisades creates at least on territory of less than 4 cells, the move is invalid.

Those territories matters are extracted in an eponymous package, out of the DDD scope. It is not the piece of code that I am the most proud of, but you can find it on the project's repository. PR welcomed, as they say!

I am not going into much details about passing a turn, the only notable thing is the end game management. The command needs to check if every player passed they turn, and ends the game if they all did via a GameFinished event. This event contains the final score, computed by a territory and a score services. As stated earlier, this is the most complex part of the application, domain insight might help me refactor it later.

End of a game

We are almost done with the basic rules! The only missing part is the ability to end the game, and provide a scoreboard.

The guide indicate us that the game ends once every player have passed they turn. We can represent that with a GameFinished event. It has to be checked every time a player pass, so we can add that to the PassTurn command:

func nextPlayerOrEndGame(history []event.Event) event.Event {
    currentGame := game.ReplayHistory(
        append(history),
    )
    for _, player := range currentGame.Players() {
        if !player.TurnPassed() {
            return event.NextPlayer{}
        }
    }

    territories, _ := board.FindTerritories(currentGame.Board())

    return event.GameFinished{
        Scores: score.ComputeScores(territories),
    }
}

Again, the complexity of score computing is extracted in its own package, along with ties management.

The GameFinished event is handled by the game by changing his state and adding the scores:

func (g game) ApplyGameFinished(event event.GameFinished) Game {
    g.state = Finished
    g.scores = event.Scores
    return g
}

There we go, three pages of rules implemented following the nomenclature!

What is next?

You may have noticed, this article is focused on the domain concerns. As the application was built with agility in mind, every part was delivered with the corresponding front-end client. This front-end is barebones and I still need to build a real responsive Web App with the game's assets before delivering the V1.

Another area of improvement is on the infrastructure part. The Go application is stateful, with the events and the parties stored in memory. These information will need to be extracted in any sort of repository and the application will have to fetch those data on every request. It will make the application Serverles-ready and more easy to deploy.

After that, a continuous delivery pipeline will have to be built to facilitate the first release and the following ones.

I think that there is also some work to be done on the client-server relationship. The client still have too many responsibilities in my opinion, and it would be great for the server to send him available moves for example. Using the right protocol for this turn-base game is also important to me, the persistent connection of the Web Sockets seems exaggerated.

Advances rules are still to be implemented, such as the team-play for four players or the integration of reinforcement and race's powers.

What to get out of this experience

It was a really great experience for me! Building the game with DDD patterns and following TDD principles made the process feel more natural.

There is no translation from and to domain terms thanks to the ubiquitous language. The testing was very explicit thanks again to domain events. In the end, I found the domain source code to be more obvious and to the point.

I am still frustrated about the deployment part, which is still not done by the time I am writing, but it was out of the score of this whole experience.

To conclude, I cannot recommend you enough to read about DDD and try it out yourself!

Introduction to Svelte - Adapting a board game

Thomas Ferro — Tue, 14 Jan 2020 12:08:36 +0000

Or how being trollish almost made me skip a gem.

Yet another state of JS

Extracted from the 2019 survey of "State of JS - Front-End frameworks"

So, you want to build a Web application? You have been searching for the best tool to do the job, reading articles and tech radars? The landscape has not change that much since 2019, with three behemoths dominating the market.

React, Angular and Vue, three frameworks (and associated cults) with quite a similar promise : helping us build reactive application, while taking full advantage of the components approach.

I will not be able to talk much about Angular and React, since I have chosen to focus on Vue for the last three years. I bet that you will be able to do the analogy of what I will say with the framework of your heart.

It is common knowledge that Vue.js is the one of the three with the cheapest entry cost. I agreed with this statement for a long time, preaching for my parish as we developers do. Yet, as time goes by, I found myself being more critical about the Vue approach.

I have been teaching Vue for about a year now, and every time I do, I lost some of the students with all of the concepts. The issue is not that there are too many of them, but everyone comes with caveat, exception and sometimes different syntax. It is very confusing for people trying to start using the framework.

Those "issues" can be described as the entry cost of Vue.js. Yet, the more I think about those pain points, the more I feel that we developers pay the price of the technical complexity that should be abstracted by the framework. When learning Vue you will eventually get over it, but why should we?

Please note that I am talking about Vue 2.x. The Composition API might be the solution, but I have yet to try it.

I do not know if the same can be said about the other two, please let me know your point of view on this matter!

The native way

Are native Web Components a thing? I would love to believe that. No framework shipped to the user, only a standard way of creating, exposing and using components!

But let's be honest, we are far from it. Far from building our complex applications with no framework. The current state of the art is to ship lots and lots of dependencies for our application to run. The more Javascript the better!

The standard way is stillborn. Or is it?

What about Svelte?

"Svelte, you say? Another contender? What is it going to be, two months or three until we all forget about it?" These were my first thoughts when I heard about Svelte.

"Cybernetically enhanced web apps? Was there no other marketing nonsense available?" These were my thoughts when I landed on the tool's website.

"Wait, that's actually a great set of promises!" These were my thoughts when I finished reading the main page.

"Wow, it must be the best tutorial I have ever seen!" These were my thoughts when I finished reading the tutorials.

Remember my laments about the current state of JS? About native Web Components? Turns out I might have been missing the tool that meets my expectations.

Svelte is not like the golden three frameworks. Instead of doing the heavy lifting in the browser like React, Vue and Angular, Svelte does it in compile time. Instead of shipping the framework to the user, we only ship native Web Components.

The only concern that I have is with compatibility. What about browser that does not support Web Components APIs? (I have yet to double-check on this)

Before we start, what is Armadora

Todo lists applications are ok. They are certainly more valuable than Hello Worlds for learning, but I much prefer a bigger project. I know that games are usually created using 2d or 3d drawing libraries, but I thought that a HTML game would be just fine for my objective : to adapt a board game as a Web application.

Armadöra is a game designed by Christwart Conrad, helped by artist Tony Rochon.

Here is the description of the game, as stated in the game's guide:

True to their reputation, Dwarfs amassed a large amount of gold. Armadöra thus became a highly coveted land for Elves, Orcs, Goblins and Mages who are all now assembling their respective forces. Let the siege of Armadöra begin!

Position your troops, raise the barricades, but make no mistake about it, a single error may undermine your strategy!

I would like to thank Blackrock Games, the game's editor, for allowing me to use their property for educational purpose.

How to start?

Before starting any project of your own, I cannot recommend you enough to read and play through the tutorials. They are well written, straight to the point and it does not require too much time. It took me a couple of hours, but I think that it was thanks to my Vue.js background.

I will describe every interesting parts of the making of the game in order to introduce you to Svelte's beauties.

The first part might be the least interesting, the setup. Between you and me, I don't like setups. It's coarse and rough and irritating and it gets everywhere. Not like with Svelte's setup tool.

The Vue ecosystem makes a great job at abstracting the setup and the configuration with Vue CLI. I was not expecting to find a similar tool with Svelte, but I was wrong (well, for projet initialization at least).

One way to bootstrap a Svelte project is by using the degit package, who provides application templates for you to use. I did not use the tool for anything else yet, but the job I asked it to do was well done. Isn't what a tool is supposed to do?

Simply install the dependencies (npm install) then run the npm run dev command and you are up and running!

Svelte 101

Now that we have a working application, let me introduce .svelte files. Similar to .vue files in guess what ecosystem, those files allow you to describe a component that can be used anywhere you like.

Well, describe might not be the best choice of word. A description of a component is what you do when using the Vue syntax for instance.

With Svelte, there is no heavy descriptive syntax to use. You want a data named applicationName? How would you do it with plain old Javascript? You are right, with a variable.

<script>
  const applicationName = 'Armadora' 
</script>

That is all for me, thanks for reading, bye bye!

Jokes aside, it feels really good not to learn a heavy syntax for such simple tasks. There will be some to learn, but not for simple purposes like that.

Now, you want to display the variable value in the browser? Go on and interpolate it in the template!

<h1>{applicationName}</h1>

Any code in the curly braces is Javascript ran in the context of your component. You can write anything you want, even trying to do math in JS: {0.1 + 0.2}.

Going back to our example, in the App.svelte component (for now), if we want to display the number of palisades left, it will look something like this :

<script>
  let palisadesLeft = 35
</script>

<main>
  Palisades left: {palisadesLeft}
</main>

Actions and dynamic attributes

You can argue that what we have done so far is nothing more than a static page made with way more tools than necessary. You will be right. You impatient reader.

To make the magic happen, let us add some interactions.

The game's implementation is going to be way more complex, but for know we are going to say that for a player to put a palisade, he just have to click a button. Such fun, I know.

You can, in vanilla Javascript, listen for a DOM event in an element. For instance, listening to a click on a button will look like this:

document.querySelector('button').addEventListener('click', methodCalledOnClick)

This syntax is simplified with Svelte:

<button on:click={methodCalledOnClick}>Click me if you dare!</button>

Of course, every DOM event can be listened for.

Before applying this concept, remember what I said about the variables? That simply declaring them makes them available in the HTML template? Well, the same goes for the functions!

Decrement our palisade count will therefore be done this way:

<script>
  let palisadesLeft = 35

  const putPalisade = () => palisadesLeft--
</script>

<main>
  Palisades left: {palisadesLeft}
  <button on:click={putPalisade}>Put a palisade</button>
</main>

"Wait a minute", I hear you say, "We can go below zero and have minus 20 palisades left ! We trusted you Thomas !"

Baby steps ! Now that we have a button, we can make the putPalisade method a bit smarter, and we can also introduce a new concept: dynamic attributes.

Remember when we interpolate JS variable into the template as text to be displayed? Well, we can do just that with HTML attributs to !

You want to dynamically disable a button, based on a JS variable? Let's do it !

<button disabled={shouldTheButtonBeDisabled}>My awesomely pointless button</button>

In our palisades example, it will look something like this:

<script>
  let palisadesLeft = 35
  let hasPalisadesLeft = true

  const putPalisade = () => {
    if (palisadesLeft > 0) {
        palisadesLeft--
    }
    hasPalisadesLeft = palisadesLeft > 0
  }
</script>

<main>
  Palisades left: {palisadesLeft}
  <button on:click={putPalisade} disabled={!hasPalisadesLeft}>Put a palisade</button>
</main>

Any HTML attribute can be made dynamic with this technique.

If your hair stood up while seeing the hasPalisadesLeft variable, hold your horses, we will discuss this just now !

To reactivity and beyond !

This hasPalisadesLeft business smells. Having to manage multiple data for something that clearly could be computed (excuse my Vue) seems like a lot of work.

Is there any way to have a variable that is automatically recomputed when any of the dependency changes? Of course it is, I would have swept it under the carpet otherwise.

I have to say, the syntax of this feature bugs me a little, but here is how we do it using labels. In this example, the fullname will be recomputed whenever the firstname or lastname changes:

<script>
    let firstname = 'Thomas'
    let lastname = 'Ferro'

    $: fullname = `${firstname} ${lastname}`
</script>

<span>{fullname}</span>

We can go even further and creating a whole function that will be called again if any dependency changes:

<script>
    let firstname = 'Thomas'
    let lastname = 'Ferro'

    $: {
        console.log(firstname, lastname);
    }
</script>

What does any of these reactivity magic have to do with our hasPalisadesLeft? Well, as I said earlier, this data is simply another representation of the palisadesLeft count. So we can make a reactive data instead of setting it manually:

<script>
  let palisadesLeft = 35

  $: hasPalisadesLeft = palisadesLeft > 0

  const putPalisade = () => {
    if (palisadesLeft > 0) {
        palisadesLeft--
    }
  }
</script>

<main>
  Palisades left: {palisadesLeft}
  <button on:click={putPalisade} disabled={!hasPalisadesLeft}>Put a palisade</button>
</main>

Conditional rendering and looping

One common need in templating is the ability to render parts of HTML only if a predicate condition is met. One will achieve that in Svelte with the #if, :else if and :else keywords.

<script>
    const displayContent = true
</script>

{#if displayContent}
<h1>My content !</h1>
{:else}
The content cannot be displayed.
{/if}

As the tutorial says:

A # character always indicates a block opening tag. A / character always indicates a block closing tag. A : character, as in {:else}, indicates a block continuation tag. Don't worry — you've already learned almost all the syntax Svelte adds to HTML.

Where to put that in practice in our application? Pretty much everywhere. Let us say that we have to display the winner at the end of the game, a big old if can do the trick !

<script>
    const winner = 'Orcs'
    // [...]
</script>

{#if !winner}
[The game board and controls...]
{:else}
<section class="winner-display">
    {winner} wins !
</section>
{/if}

Another thing you can do is to repeat some part of the template based on data. You will do that with the each keyword.

<script>
  const blogPosts = [
        'My first article',
        'Why my first article was dumb',
        'Is my second article to trust?',
        'Lesson learned - or why will I never blog again',
    ]
</script>

<main>
    <h1>My blog !</h1>
    {#each blogPosts as post}
    <article>
        <h2>{post}</h2>
    </article>
    {/each}
</main>

You can put whatever you need inside the loop, and you also have access to the index as the second argument.

Note: There is a notion of keyed each blocks that I will let you discover afterwards.

Displaying every player can be a good example of use-case:

<script>
    const players = [
        {
            character: 'Orc',
            nickname: 'README.md'
        },
        {
            character: 'Elf',
            nickname: 'Javadoc'
        },
        {
            character: 'Mage',
            nickname: 'noobmaster69'
        },
    ]
</script>

{#each players as player}
<section class="player">
    {player.nickname} playing {player.character}
</section>
{/each}

Here, player can be destructured to directly access the attributes:

<script>
    const players = [
        {
            character: 'Orc',
            nickname: 'README.md'
        },
        {
            character: 'Elf',
            nickname: 'Javadoc'
        },
        {
            character: 'Mage',
            nickname: 'noobmaster69'
        },
    ]
</script>

{#each players as { nickname, character }}
<section class="player">
    {nickname} playing {character}
</section>
{/each}

More bindings

Remember the time when creating a form and fetching the data from it in Javascript was obnoxious? All the events to listen for, all the data to maintain up-to-date... Those days are long gone now with the help of inputs bindings !

You can see those binding as a way to connect a JS variable to a HTML input. When updating the value, the field will be updated and vice versa.

This feature can be used with many types of inputs, from the simple text to a select with multiple values. In any of those cases, you will use the bind:value syntax as follow:

<script>
    let name = 'world';
</script>

<input type="text" bind:value={name}>

<h1>Hello {name}!</h1>

I will not go into much details here since all I can do is paraphrase the documentation or the tutorial.

What I will do, however, is to continue implementing the game ! Input bindings can be useful with "New player form", a basic form with a name and the chosen character:

<script>
    let nickname = ""
    let character = undefined

    let availableCharacters = [
        'Orc',
        'Elf',
        'Mage',
        'Gobelin'
    ]
</script>

<ul>
    <li>Nickname: {nickname}</li>
    <li>Character: {character}</li>
</ul>

<form>
    <label>
        Nickname
        <input type="text" bind:value={nickname}>
    </label>
    <label>
        Character
        <select bind:value={character}>
            {#each availableCharacters as availableCharacter}
            <option value={availableCharacter}>{availableCharacter}</option>
            {/each}
        </select>
    </label>
</form>

The elephant in the room - What about components?

For maintainability, testability and whateverotherwordsthatendswithbility, we developers tend to split our applications in small modules. Many years of Clean Code made us think that for a module to be efficient, we need it to be small, self-contained and reusable if possible. These principle can also be applied in front-end development via the use of components.

Luckily enough, we already have played with components since the beginning of our Svelte course ! In fact, every .svelte file represent a component.

We will go through the process of creating a new component, to importing and using it and then we will see how we can manage communication between components.

To create a new component, go ahead and create a new MyFirstComponent.svelte file next to the App.svelte (for now, we will clean up our rooms later). In that new file, you can apply every principle that we have seen so far ! We can for instance have internal data, bind those data in the template, etc.

<!-- MyFirstComponent.svelte -->
<script>
  const title = "My first component !!!!"
</script>

<article>
    {title}
</article>

Great, now we have a component ! Next step is to import and use it. Let us say that we want this new component to be displayed in App.svelte. The first thing to do is to import the component, just like a JS module:

<!-- App.svelte -->
<script>
    import MyFirstComponent from './MyFirstComponent.svelte'
</script>

We can now use the component in the template, just like any other HTML tag !

<!-- App.svelte -->
<script>
    import MyFirstComponent from './MyFirstComponent.svelte'
</script>

<MyFirstComponent></MyFirstComponent>

For a more concrete example, let us extract the display of a player in a Player.svelte component:

<!-- Player.svelte -->
<section class="player">
    A player...
</section>

Oh.. Seems like we need to receive data about a player in order to display them in this component.. How could we manage to do that?

This is the first parent-child communication tool that we will see: Props are used to communicate from the parent to a child. A props is nothing more than a variable, it can be a string, a number or any complex object. Here is how to declare a props:

<!-- Player.svelte -->
<script>
    export let character
    export let nickname
</script>
<section class="player">
    <!-- Props can be used just like any internal data -->
    {nickname} playing {character}
</section>

As implied in the name, you need to provide data from the parent to effectively have a "parent-child communication".

You can do so by adding attributes when calling the custom component. Yes, just like any native HTML attribute:

<!-- App.svelte -->
<script>
    import Player from './Player.svelte'
</script>

<Player character="Orc" nickname="README.md"></Player>

Here, I set the value of the attributes manually, but nothing prevent us from binding values ! The reactivity black-magic will do the trick and any modification in the data of the parent will be reported in the children.

<!-- App.svelte -->
<script>
    import Player from './Player.svelte'

    const players = [
        {
            character: 'Orc',
            nickname: 'README.md'
        },
        {
            character: 'Elf',
            nickname: 'Javadoc'
        },
        {
            character: 'Mage',
            nickname: 'noobmaster69'
        },
    ]
</script>

{#each players as player}
<Player character={player.character} nickname={player.nickname}></Player>
{/each}

We have ourselves a working one-way data flow ! Try to code a form to add a player and see what happen !

... Wait... "one-way data flow"? What about the other way? There is another way?

We only have cover the parent to children communication, but there are use-cases when a component needs to talk to his parent. How to do that without breaking the golden rules of components? How could a component be self-contained if he needs to know whom his parent is? You can achieve that by dispatching events.

The mantra for parent-child communication - and it applies to Vue.js too - is the following: Props down / Events up.

The first thing you will need to do is to create an event dispatcher, using Svelte's exposed methods:

<!-- Child.svelte -->
<script>
    import { createEventDispatcher } from 'svelte';

    const dispatcher = createEventDispatcher();
</script>

Then, when you want to dispatch an event, call the dispatcher with the name of the event as the first argument.

<!-- Child.svelte -->
<script>
    import { createEventDispatcher } from 'svelte';

    const dispatcher = createEventDispatcher();

    const sendEvent = () => {
        dispatcher('my-custom-event')
    }
</script>

<button on:click={sendEvent}>Send event !</button>

You can also send data through the event with the second argument. Those data are often referred to as the payload and can be of any type you need.

Note: The payload can be retrieve in the detail attribute in the actual event.

<!-- Child.svelte -->
<script>
    import { createEventDispatcher } from 'svelte';

    const dispatcher = createEventDispatcher();

    const sendEvent = () => {
        dispatcher('my-custom-event', {
            name: 'Thomas',
        })
    }
</script>

<button on:click={sendEvent}>Send event !</button>

Let us say that we are creating a form, which can take the default name and age as props. The form is not responsible for the data, it is not his duty to modify them. When the form is complete, the child component will send an event, notifying his parent that the job is done:

<!-- ClientForm.svelte -->
<script>
  import { createEventDispatcher } from 'svelte';

  const dispatcher = createEventDispatcher();

    export let name = undefined
    export let age = undefined

    let newName = undefined
    let newAge = undefined

    $: newName = name
    $: newAge = age

    const validate = () => {
        dispatcher('validate', {
            name: newName,
            age: newAge,
        })
    }
</script>

<input type="text" bind:value={newName}>
<input type="number" bind:value={newAge}>
<button on:click={validate}>
    Validate
</button>

<!-- App.svelte -->
<script>
    import ClientForm from './ClientForm.svelte';
    let name = 'Thomas'
    let age = 24

    const updateData = (payload) => {
        name = payload.name
        age = payload.age
    }
</script>

<ul>
    <li>Name: {name}</li>
    <li>Age: {age}</li>
</ul>

<!-- Here we need to fetch the 'detail' attribute from the event -->
<ClientForm name={name} age={age} on:validate={(event) => updateData(event.detail)}></ClientForm>

Another example: building a grid

Before we wrap up, let me show you another example with the game's grid.

This grid is composed of cells in which you can click to put a warrior.

The cell can either contain a warrior, gold or it can be empty. We will abstract that by saying that it receive a content and we will be simply displaying the content. When clicking on a cell, the component simply propagate the event via the shortcut on:click.

<!-- Cell.svelte -->
<script>
    export let content;
</script>

<button on:click>
    {content}
</button>

The grid component receive the state of each cell from his parent, via the state attribute which is a two dimensional array. It manages the click on a cell by emitting an event for his parent to listen.

<!-- Grid.svelte -->
<script>
    import { createEventDispatcher } from 'svelte';
    import Cell from './Cell.svelte';

    export let state;

    const dispatch = createEventDispatcher();

    const cellClicked = (rowIndex, colIndex) => {
        dispatch('cell-selected', {
            row: rowIndex,
            col: colIndex,
        })
    }
</script>

<article class="grid">
    {#each state as row, rowIndex}
    <section class="row">
        {#each row as cell, colIndex}
            <Cell
                content={cell}
                on:click={() => cellClicked(rowIndex, colIndex)}
            ></Cell>
        {/each}
    </section>
    {/each}
</article>

The root component App.svelte is responsible for the actual data, changing the state of the grid when it receives an event from the grid. It is not the responsibility of the grid nor the cell to change the state.

<!-- App.svelte -->
<script>
    import Grid from './Grid.svelte';

    const state = [
        [ 'land', 'land', 'land', 'land', 'land', 'land', 'land', 'land' ],
        [ 'land', 'land', 'land', 'land', 'land', 'land', 'land', 'land' ],
        [ 'land', 'land', 'land', 'land', 'land', 'land', 'land', 'land' ],
        [ 'land', 'land', 'land', 'land', 'land', 'land', 'land', 'land' ],
        [ 'land', 'land', 'land', 'land', 'land', 'land', 'land', 'land' ],
    ]

    const cellSelected = (payload) => {
        // Change the state based on the payload, the current player and the chosen action
        state[payload.row][payload.col] = 'warrior'
    }
</script>

<Grid state={state} on:cell-selected={(e) => cellSelected(e.detail)}></Grid>

This is a simplified example of how those concepts can all fit together in a real application. The game's rules are not implemented to avoid noise, the point here is to show you parent-child communication in action.

Now that you have the building blocks of an application, all you have to do is build your own ! Try to build this game or any other, or even a more traditional Web application :)

Disclaimers

The components and examples from this article are for studying purpose only. Building the actual game would require some kind of server with the game data to which every player will connect and interact with. However, I hope that it gives you a good idea of what you can do with Svelte !

Please refer to the game's repository if you want to take a look at the current state of the game.

I purposely did not discussed what I consider to be advanced topics, such as class binding, transitions, lifecycle or slots. Please read through the documentation and build some projects on your own to fully discover the tool !

Wrapping up !

You may have noticed, I am really getting into Svelte. The promises are in line with my own opinions about Javascript frameworks and the Web at large, and it feels just good writing applications with this tool.

I might not recommend it for every use-case yet, especially not knowing how it behave on old browsers. However, it is definitely worth learning if you feel tired of the Reacts, the Angulars and the Vues or just if you want to get into front-end development !