Another thing is the API of modern CSS frameworks. Bootstrap's APIs and CSS classes were very simple to keep in your head. But today, whenever I develop using such a framework, I have to have the documentation of Vuetify, Material UI or whatever open at all times, getting ready to copy paste 50 lines of code for a simple dialog. There is no way I will remember all the props, scopes, events, etc. of each component. This whole copy paste action also takes away the fun to be honest.

Ever since I started using the low level utility-first CSS framework Tailwind, working with anything else feels unproductive. I've written a blog post on it here. Sure, at first you need to look at the documentation, but it's API is predictable and easy to remember, also there are tools for autocompletion available. The best thing is that it is completely framework agnostic. No new API to learn just because you decide to use React over Vue in your next project.

Next, let's create the CSS file that tailwind places all the classes inside. You could also add it to a vue file, but I didn't get it to work with purgeCSS which we will need to reduce the CSS to only the minimum.

Here is the code

/* resources/assets/css/app.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

Now, let's instruct tailwind to create the config file, which we will tinker with later

npx tailwindcss init

To complete the basic setup follow step 4 here. This highly depends on your build setup. For example, I use laravel-mix to compile my assets, so I added the following to my webpack.mix.js file:

mix.postCss('resources/assets/css/app.css', 'public/css', [
    require('tailwindcss'),
    require('autoprefixer'),
]

Don't forget to import the css file in your HTML

Customizations

Tailwind should already work by now, but your project's layout probably changed here and there. There are two steps we have to take here:

1. Add a prefix to our tailwind classes
2. disable preflight

Some classnames are clashing between tailwindcss and vuetify. To avoid this, head over to the previously generated tailwind.config.js and add a prefix

module.exports = {
  prefix: 'tw-',
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

This means that, for example, instead of the class flex, the class name in your project will be tw-flex.

Next, tailwindcss gets rid of some cross-browser inconsistencies for us by default, but vuetify is doing the same thing already, so it's better to disable preflight in tailwindcss. Go back to tailwind.config.js and add:

module.exports = {
  corePlugins: {
    preflight: false,
  },
  prefix: 'tw-',
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

PurgeCSS

So far so good, let's tackle the last problem. TailwindCSS creates thousands of CSS classes, so if you take a look at your bundle size, it increased quite significantly! We can overcome this by adding purgeCSS, this will get rid of any unused CSS for us.

Note: Newer versions of Tailwind already come with purgeCSS support. Check the docs: https://tailwindcss.com/docs/controlling-file-size

First, install the package

npm install @fullhuman/postcss-purgecss --save-dev

Next, add it to your postCSS plugins (from tailwind documentation)

const purgecss = require('@fullhuman/postcss-purgecss')({
    // Specify the paths to all of the template files in your project 
    content: [ './resources/assets/js/**/*.vue' ],

    css: ['./resources/assets/css/app.css'],

    // Include any special characters you're using in this regular expression
    defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
})

mix.postCss('resources/assets/css/app.css', 'public/css',[
    require('tailwindcss'),
    require('autoprefixer'),
    purgecss,
])

And go to app.css and tell purgeCSS not to purge tailwind's base classes

/* purgecss start ignore */
@tailwind  base;
@tailwind  components;
/* purgecss end ignore */

@tailwind utilities;

Now let it compile and you will find your application in a very sad state with all the vuetify styles being removed :o

Right, so we need to tell purgeCSS to leave vuetify alone.

To do that head over to your main javascript file where you import vuetify's CSS like this:

import 'vuetify/dist/vuetify.min.css'

Get rid of it :)

Instead, let's add the import to our app.css file inside the purgecss ignore block

/* purgecss start ignore */
@import 'vuetify/dist/vuetify.min.css';
@tailwind  base;
@tailwind  components;
/* purgecss end ignore */

@tailwind utilities;

In order for "@import" to work we need to install a custom package

npm install postcss-import

and register it in postCSS

mix.postCss('resources/assets/css/app.css', 'public/css',[
    require('tailwindcss'),
    require('autoprefixer'),
    require("postcss-import"),
    purgecss,
])

And we are almost done! You can now test it in the browser. But be aware that, at least with laravel-mix, the CSS will get purged only for the first compile. That means, if you keep a watch over changes, it will not "unpurge" new CSS classes you add. To overcome this, let's only purge our CSS when compiling for production:

mix.postCss('resources/assets/css/app.css', 'public/css',[
    require('tailwindcss'),
    require('autoprefixer'),
    require("postcss-import"),
    ...process.env.NODE_ENV === 'production' ? [purgecss] : []
])

お疲れ様です！

How it looks like

Here is the GitHub of the little app. It contains a couple of actions like getting all users, creating users, and logging in.

To keep this example simple, let's just see how we can get the list of all users.

Backend (extracted from Actions/user.js)

const User = use('App/Models/User')

exports.getAllUsers = async function() {
  return User.all()
}

Frontend (extracted from App.vue)

<template>
  <ul>
    <li v-for="user in users" :key="user.id">
      [{{ user.id }}] {{ user.email }}
    </li>
  </ul>
</template>

<script>
import { getAllUsers } from '../../api/app/Actions/user'

export default {
    data() {
        return { users: [] }
    },
    async mounted() {
        this.users = await getAllUsers()
    }
}
</script>

Seeeeamless ;)

Changes to the previous prototype

Mainly there's a new seamlesslyrc.json file that holds everything together. The backend will write all generated routes to this file and the frontend will then consume it.

Having this file comes with a lot of benefits over the previous prototype:

• No need for language/framework parsing
• single source of truth for the whole API generation
• Can be used to look up the API
• Can be used to store more things in the future like the endpoint prefix (currently always /api)
• using other HTTP methods than just POST is a lot easier.

The loader and API generator is under a new package called seamlessly.

And you can find the integration for the above example here:

• backend: https://github.com/MZanggl/adonis-vue-without-api/blob/master/api/start/routes.js
• frontend: https://github.com/MZanggl/adonis-vue-without-api/blob/master/ui/vue.config.js

There are still some things that require some more thought, but I guess for the next test, I will try to use a non-JS language as the backend. Laravel 🤔🤔🤔

Nr 2: 'Factory.model' => 'factory'

Inside vowfile.js where you set up the test environment I have added this little global helper:

const Factory = use('Factory')

global.factory = (model) => {
    return Factory.model(model)
}

So instead of writing

const Factory = use('Factory')
Factory.model('App/Models/User').create()

we can now do

factory('App/Models/User').create()

It's again a way to save some keystrokes. While globals are considered harmful, there are some use cases and there is no problem to use globals when the price is right.

I like to make not too many modifications to the framework as it can make upgrading more difficult and the project becomes more custom in general, so I try to keep such things to a minimum and only apply them after a long trial period with the things the framework provides by default.

We want to focus on four objectives when it comes to code improvements

• avoiding temporary variables
• avoiding conditionals
• be able to think of your code in steps
• reveal intent

We will highlight the most important methods on the Array prototype (leaving out basic array manipulation like push, pop, splice or concat) and hopefully you will find scenarios where you can apply these instead of the following usual suspects.

for loop

for (let i = 0; i < users.length; i++) {
    //
}

Array.prototype.forEach

users.forEach(function(user) {
    //
}

ES6 for of Loop

for (const user of users) {
    //
}

One more thing before we get started!

If you are unfamiliar with ES6 arrow functions like:

users.map(user => user.name)

I recommend you to take a look at those first. In summary, the above is very similar, and in this case, the same as

users.map(function(user) {
   return user.name
})

Array.prototype.filter

Let's say we want to find all users that are active. We briefly looked at this in the introduction of the article.

const activeUsers = []

users.forEach(user => {
  if (user.active) {
    activeUsers.push(user)
  }
})

If we look back at the four objectives we set before, it is very obvious that this is violating at least two of them. It has both temporary variables as well as conditionals.

Let's see how we can make this easier.

const activeUsers = users.filter(user => user.active)

The way Array.prototype.filter works is that it takes a function as an argument (which makes it a higher order function) and returns all users that pass the test. In this case all users that are active.

I think it is safe to say that we were also able to reveal our intent. forEach can mean anything, it might save to the database, etc. while filter does what the name suggests.

Of course you can also use filter on a simple array. The following example would return all animals starting with the letter a.

['ape', 'ant', 'giraffe'].filter(animal => animal.startsWith('a'))

A use case I also see often is removing items from an array. Imagine we delete the user with the id 1. We can do it like this

users = users.filter(user => user.id !== 1)

Another use for filter is the following

const result = [true, 1, 0, false, '', 'hi'].filter(Boolean) 
result //? [true, 1, 'hi']

This effectively removes all falsy values from the array. There is no magic going on here. Boolean is a function that takes an argument to test whether it is truthy or not. E.g. Boolean('') returns false, while Boolean('hi') returns true. We simply pass the function into the filter method, so it acts as our test.

Array.prototype.map

It often happens that we have an array and want to transform every single item in it. Rather than looping through it, we can simply map it. Map returns an array with the same length of items, it's up to you what to return for each iteration.

Let's create an array that holds the usernames of all our users.

Traditional loop

const usernames = []

users.forEach(user => {
  usernames.push(user.name)
})

Mapping it

const usernames = users.map(user => user.name)

We avoid temporary variables and reveal intent at the same time.

Chaining

What is great about these higher order functions is that they can be chained together. map maps through an array and returns a new array. filter filters an array and returns a new array. Can you see a pattern? With this in mind, code like the following becomes not only possible but very readable

const activeUsernames = users
  .filter(user => user.active)
  .map(user => user.name)

And with this we complete our final objective to think in steps. Rather than thinking out the whole logic in your head, you can do it one step at a time. Think of the example we had at the very start.

const activeUsernames = []

users.forEach(user => {
  if (user.active) {
    activeUsernames.push(user.name)
  }
})

When you read this for the first time, in your mind the process would go somewhat like

- initialize an empty array
- loop through all users
    - if user is active
        - push to the array from the beginning
            - but only the name of the user
- repeat

With the refactored method it looks more like this

- get all active users
- create new array of the same size
    - that only hold their username

That's a lot easier to think and reason about.

There are many more interesting methods available. Let's check out some more.

Array.prototype.find

The same way filter returns an array with all the items that pass the test, find returns the first item that passes the test.

// returns user with id 1
users.find(user => user.id === 1)

Array.prototype.findIndex works the same way but it returns the index instead of the item

For arrays that don't require deep checking there is no need to have the overhead of an extra function, you can simply use includes and indexOf respectively.

['a', 'b', 'c'].includes('b') //? true
['a', 'b', 'c'].indexOf('a') //? 0
['a', 'b', 'c'].includes('d') //? false
['a', 'b', 'c'].indexOf('d') //? -1

Array.prototype.some

Returns true if at least one test passes. We can use this when we want to check if at least one user in our array is active.

Traditional solution using for loop

let activeUserExists = false
for (let i = 0; i < users.length; i++) {
  if (users[i].active) {
    activeUserExists = true
    break
  }
}

Solution using some

users.some(user => user.active)

Array.prototype.every

Returns true if all items pass the test. We can use this when we want to check whether all users are active or not.

Traditional solution using for loop

let allUsersAreActive = true
for (let i = 0; i < users.length; i++) {
  if (!users[i].active) {
    allUsersAreActive = false
    break
  }
}

Solution using every

users.every(user => user.active)

Array.prototype.reduce

If none of the above functions can help you, reduce will! It basically boils down the array to whatever you want it to be. Let's look at a very simple implementation with numbers. We want to sum all the numbers in the array. In a traditional forEach loop it would look like this:

const numbers = [5, 4, 1]
let sum = 0
numbers.forEach(number => sum += number)
sum //? 10

But the reduce function takes away some of the boilerplate for us.

const numbers = [5, 2, 1, 2]
numbers.reduce((result, number) => result + number, 0) //? 10

reduce takes two arguments, a function and the start value. In our case the start value is zero. If we would pass 2 instead of 0 the end result would be 12.

So in the following example

const numbers = [1, 2, 3]
numbers.reduce((result, number) => {
    console.log(result, number)
    return result + number
}, 0)

the logs would show:

• 0, 1
• 1, 2
• 3, 3

with the end result being the sum of the last two numbers 3 and 3, so 6.

Of course we can also reduce our array of objects into, let's say a hashmap.

Grouping by the group key, the resulting hashMap should look like this

const users = {
  1: [
    { id: 1, name: 'Michael' },
  ],
  2: [
    { id: 2, name: 'Lukas' },
  ],
}

We can achieve this with the following code

users.reduce((result, user) => {
  const { group, ...userData } = user
  result[group] = result[group] || []
  result[group].push(userData)
  
  return result
}, {})

• const { group, ...userData } = user takes the group key from the user, and puts the remaining values inside userData.
• With result[group] = result[group] || [] we initialize the group in case it doesn't exist yet.
• We push userData into the new group
• We return the new result for the next iteration

Using this knowledge on other iterables and array-like objects

Do you remember this from before?

for loop: works on array-like objects

for (let i = 0; i < users.length; i++) {
    //
}

Array.prototype.forEach: method on the array prototype

users.forEach(function(user) {
    //
}

ES6 for of Loop: works on iterables

for (const user of users) {
    //
}

Did you realize how significantly different the syntax of the forEach and the two for loops are?

Why? Because the two for loops do not only work on arrays. In fact they have no idea what an array even is.

I am sure you remember this type of code from your CS classes.

const someString = 'Hello World';
for (let i=0; i < someString.length; i++) {
    console.log(someString[i]);
}

We can actually iterate through a string even though it is not an array.

This kind of for loop works with any "array like object", that is an object with a length property and indexed elements.

The for of loop can be used like this

const someString = 'Hello World';
for (const char of someString) {
    console.log(char);
}

The for of loop works on any object that is iterable.

To check if something is iterable you can use this rather elegant line Symbol.iterator in Object('pretty much any iterable').

This is also the case when dealing with the DOM. If you open the dev tools right now and execute the following expression in the console, you will get a nice red error.

document.querySelectorAll('div').filter(el => el.classList.contains('text-center'))

Unfortunately filter does not exist on iterable DOM collections as they are not Arrays and therefore don't share the methods from the Array prototype. Want proof?

(document.querySelectorAll('div') instanceof Array) //? false

But it is an array like object

> document.querySelectorAll('.contentinfo')

    NodeList [div#license.contentinfo]
        0: div#license.contentinfo
        length: 1
        __proto__: NodeList

and is also iterable

Symbol.iterator in Object(document.querySelectorAll('div')) //? true

If we want to use our newly trained Array knowledge on let's say iterable DOM collections, we have to first turn them into proper arrays.

There are two ways of doing it.

const array = Array.from(document.querySelectorAll('div'))

or

const array = [...document.querySelectorAll('div')]

I personally prefer the first way as it provides more readability.

Conclusion

We went through the most important methods on the array object and took a look at iterables. If we look back to the objectives we set at the start, I think it is safe to say that we at least accomplished

• thinking in steps
• avoiding temporary variables
• avoiding conditionals

But I am not fully satisfied with reveal intent.

While

const usernames = users.map(user => user.name)

is definitely much more readable than

const usernames = []

users.forEach(user => {
  usernames.push(user.name)
})

wouldn't

const usernames = users.pluck('name')

be even nicer?

In the next article, we will take a look at subclassing arrays, so we can provide exactly such functionality. It will also be a great entry point for unit testing with Node.js, so stay tuned.

P.S. if you are a fan of Laravel, please take a look at Laravel Collections.

We start off with (a little improved version of) the code from last time:

module.exports = function createIoC(rootPath) {
    return {
        _container: new Map,
        _fakes: new Map,
        bind(key, callback) {
            this._container.set(key, {callback, singleton: false})
        },
        singleton(key, callback) {
            this._container.set(key, {callback, singleton: true})
        },
        fake(key, callback) {
            const item = this._container.get(key)
            this._fakes.set(key, {callback, singleton: item ? item.singleton : false})
        },
        restore(key) {
            this._fakes.delete(key)
        },
        _findInContainer(namespace) {
            if (this._fakes.has(namespace)) {
                return this._fakes.get(namespace)
            }

            return this._container.get(namespace)
        },
        use(namespace) {
            const item = this._findInContainer(namespace)

            if (item) {
                if (item.singleton && !item.instance) {
                    item.instance = item.callback()
                }
                return item.singleton ? item.instance : item.callback()
            }

            return require(path.join(rootPath, namespace))
        }
    }
}

The idea is to avoid newing up classes manually and using a new method ioc.make instead. Let's write the simplest test we can think of.

describe('auto injection', function() {
    it('can new up classes', function() {
        const SimpleClass = ioc.use('test/modules/SimpleClass')
        const test = ioc.make(SimpleClass)
        expect(test).to.be.instanceOf(SimpleClass)
    })
})

And SimpleClass looks like this

// test/modules/SimpleClass.js

class SimpleClass {}

module.exports = SimpleClass

Running the test should fail because we have not yet implemented ioc.make. Let's implement it in index.js

const ioc = {
    // ...
    make(object) {
        return new object
    }
}

The test passes! But it is a little annoying to always have to first do ioc.use and then ioc.make to new up classes. So let's make it possible to pass a string into ioc.make that will resolve the dependency inside.

A new test!

it('can make classes using the filepath instead of the class declaration', function() {
    const test = ioc.make('test/modules/SimpleClass')
    expect(test).to.be.instanceOf(ioc.use('test/modules/SimpleClass'))
})

and ioc.make becomes

if (typeof object === 'string') {
    object = this.use(object)
}
            
return new object

Nice! With this, we can already new up classes. And the best thing is, they are fakable because ioc.use first looks in the fake container that we can fill with ioc.fake.

With that out of the way, let's build the automatic injection mechanism. The test:

it('should auto inject classes found in static inject', function() {
        const injectsSimpleClass = ioc.make('test/modules/InjectsSimpleClass')

        expect( injectsSimpleClass.simpleClass ).to.be.instanceOf( ioc.use('test/modules/SimpleClass') )
})

And we have to create the class InjectsSimpleClass.js

// test/modules/InjectsSimpleClass.js

class InjectsSimpleClass {
    static get inject() {
        return ['test/modules/SimpleClass']
    }

    constructor(simpleClass) {
        this.simpleClass = simpleClass
    }
}

module.exports = InjectsSimpleClass

The idea is that we statically define all the classes that need to be injected. These will be resolved by the ioc container and newed up as well.

ioc.make will become:

if (typeof object === 'string') {
    object = this.use(object)
}

// if the object does not have a static inject property, let's just new up the class
if (!Array.isArray(object.inject)) {
    return new object
}

// resolve everything that needs to be injected
const dependencies = object.inject.map(path => {
    const classDeclaration = this.use(path)
    return new classDeclaration
})

return new object(...dependencies)

Not bad. But something about return new classDeclaration seems wrong... What if this injected class also has dependencies to resolve? This sounds like a classic case for recursion! Let's try it out with a new test.

it('should auto inject recursively', function() {
    const recursiveInjection = ioc.make('test/modules/RecursiveInjection')
    expect(recursiveInjection.injectsSimpleClass.simpleClass).to.be.instanceOf(
            ioc.use('test/modules/SimpleClass')
        )
    })

And we have to create a new file to help us with the test.

// test/modules/RecursiveInjection.js

class RecursiveInjection {

    static get inject() {
        return ['test/modules/InjectsSimpleClass']
    }

    constructor(injectsSimpleClass) {
        this.injectsSimpleClass = injectsSimpleClass
    }
}

module.exports = RecursiveInjection

The test will currently fail saying AssertionError: expected undefined to be an instance of SimpleClass. All we have to do is switch out

const dependencies = object.inject.map(path => {
    const classDeclaration = this.use(path)
    return new classDeclaration
})

with

const dependencies = object.inject.map(path => this.make(path))

Altogether, the make method looks like this

if (typeof object === 'string') {
    object = this.use(object)
}

// if the object does not have a static inject property, let's just new up the class
if (!Array.isArray(object.inject)) {
    return new object
}

// resolve everything that needs to be injected
const dependencies = object.inject.map(path => this.make(path))

return new object(...dependencies)

And that's pretty much it! The version in the repo handles some more things like not newing up non-classes, being able to pass additional arguments, aliasing etc. But this should cover the basics of automatic injection. It's surprising how little code is necessary to achieve this.

Middlewares

The part we want to get rid of is this here.

if (!(await Hash.verify(request.input("password"), auth.user.password))) {
  return response.status(400).json({
    message: "The entered password is not correct"
  });
}

So let's create a middleware for it.

adonis make:middleware VerifyPassword

And here is the implementation.

"use strict";
/** @type {import('@adonisjs/framework/src/Hash')} */
const Hash = use("Hash");

class VerifyPassword {
  async handle({ request, auth, response }, next, properties) {
    if (!(await Hash.verify(request.input("password"), auth.user.password))) {
      return response.status(400).json({
        message: "The entered password is not correct"
      });
    }

    await next();
  }
}

module.exports = VerifyPassword;

Next we add it to the named middlewares in start/kernel.js.

const namedMiddleware = {
  // ...
  verifyPassword: "App/Middleware/VerifyPassword"
};

All that is left now is to add the middleware to the route.

// routes.js

Route.group(() => {
  Route.post("store", "ArticleController.store")
    .middleware(["auth", "verifyPassword"])
    .validator("StoreArticle");
}).prefix("article");

This could have also been solved by extending the validator and adding another validation rule to the StoreArticle.js validator.

Events

If operations don't need to be executed immediately, we can execute them asynchroniously using Events. This is perfect for things like sending mails.

This is exactly the case with this line of code here.

await this.sendMailToFollowers(article)

First let's create an event listener:

adonis make:listener Article

This will create App/Listeners/Article.js and here is its implementation:

"use strict";

const Article = (exports = module.exports = {});
const Mail = use("Mail");

Article.registered = async article => {
  console.log('mail implementation')
};

Back in ArticleController.js let's add this line to the top:

const Event = use("Event");

All that is left now is to switch out

await this.sendMailToFollowers(article)

with this line:

Event.fire("new::article", article)

Our controller boiled down to just this.

'use strict'

const Event = use("Event");
const Article = use('App/Models/Article')
const ArticleTag = use('App/Models/ArticleTag')

class ArticleController {
    async store({ params, auth, request }) {
        const article = await Article.create({
            title: request.input('title'),
            description: request.input('description'),
            user_id: auth.user.id,
        })

        const tags = JSON.parse(request.input('tags'))
        const articleTags = tags.map(tagId => {
            article_id: article.id,
            tag_id: tagId
        })

        await ArticleTag.createMany(articleTags)
        
        Event.fire("new::article", article)

        return response.json({
            article: article.toJSON()
        })
    }
}

But we can clean this up even more. Right now, we can only create an article when going through this controller. If we need to be able to create articles in other places, e.g. commands, or simply want to make our code more testable, we can move the business logic to a service.

Services

Let's check out the implementation, there is no command for creating services.

// app/Services/ArticleService.js

'use strict'

const Article = use('App/Models/Article')
const ArticleTag = use('App/Models/ArticleTag')

class ArticleService {
    async store({ title, description, tags }, user) {
        const article = await Article.create({
            title,
            description,
            user_id: user.id,
        })

        const articleTags = tags.map(tagId => {
            article_id: article.id,
            tag_id: tagId
        })

        await ArticleTag.createMany(articleTags)

        return article
    }
}

module.exports = ArticleService

and our controller now is simply

'use strict'

const Event = use('Event')
const ArticleService = use('App/Services/ArticleService')

class ArticleController {
    constructor() {
        this.articleService = new ArticleService
    }

    async store({ params, auth, request }) {
        const article = await this.articleService.store(request.all(), auth.user)

        Event.fire("new::article", article);
 
        return response.json({
            article: article.toJSON()
        })
    }
}

No custom actions

So far we only looked at refactoring one method inside a controller. You can still end up with pretty big controllers. If your controller ends up having too many methods, you can start splitting methods into more controllers. How? By keeping the controller cruddy. You can create a resourceful controller in Adonis with the following command:

adonis make:controller YourController --resource

This way the controller has the seven default crud actions. If you need a custom action, make it cruddy and put it in a new controller. What do I mean by this exactly and how can you achieve this? Well, there's actually a whole talk about this which you can find here.

Conclusion

Great! Each part is now in its appropriate place, is easily testable and reusable. The controller simply calls each part. We were even able to decouple the context (request, auth and response) from the business logic, making the code less coupled to the framework.

Please note that none of these refactorings are strictly necessary. It is okay to get a little messy in the controller at first as you may not have a clear picture of the whole problem you are trying to solve.

But we are not protected from everything yet! Take a look at the following controller to see what we will refactor in a future article!

const Post = use('App/Models/Post')

class PostsController {
    async search({ response, request }) {    
        const query = Post.query()

        if (request.input('category_id')) {
            query.where('category_id', request.input('category_id'))
        }

        let keyword = request.input('keyword')

        if (keyword) {
            keyword = `%${decodeURIComponent(keyword)}%`
            query
                .where('title', 'like', keyword)
                .orWhere('description', 'like', keyword)
        }

        const tags = request.input('tags')
        if (tags) {
            query.whereIn('tags', tags)
        }

        const posts = await query.fetch()

        return response.json({ posts: posts.toJSON() })
    }
}

Complements/Transformations

There is a special type of rule that transforms objects. We looked at rules like "ROCK IS PUSH" which adds an ability to the rock. But you can also link two nouns.

"ROCK IS BABA" for example will turn all rock objects on the board into a Baba object. We can perform this transformation after a move like this:

for (const [subject, complement] of complements) {
  // get all ROCK objects
  for (const block of this.getBlocksFor(subject.id)) {
    // replace them with new BABA objects
    const instance = new complement.constructor(this, block.position)
    block.getCell()[block.position.z] = instance
  }
}

We get the complements from the rules, which we will look at later.

Detecting the game's progress

For winning, we can use an event listener on the Win property:

class Win extends Property {
  static onAfterLand(movingBlock, blockWithProperty, { level }) {
    if (movingBlock.hasProperty('you')) {
      level.progress = 'won'
      level.emit('has:won')
    }
  }
}

• After every move, we also call "onAfterMove" on every block with a rule again. This is to check for rules like "BABA IS YOU AND WIN" or "BABA IS HOT AND MELT"
• At that time, we also check the number of blocks with the property "YOU" and mark the progress as lost if no block is left.

UI Integration

This was the last thing I worked on, as I initially just created unit tests to test the game logic. This allowed me to instantly catch regressions and allow for safe refactoring.

test('can read vertical rules', () => {
  const level = new Level(`
    BABA,,FLAG
    IS,,IS
    YOU,,WIN
  `)

  expect(level.rules).toEqual([
    ['TEXT', 'IS', 'PUSH'], // this is an implicit rule set by default
    ['BABA', 'IS', 'YOU'],
    ['FLAG', 'IS', 'WIN'],
  ])
})

For the UI, we make our code emit events at key moments, like "after:move" to rerender the board, "has:won" to detect when the user has won, or "after:update:rules" when the rules are updated (to render the current ruleset).

We also register some keyup event listerers to allow for moving and undoing!

level.on('has:won', () => {
  alert('you have won!')
})
level.on('after:move', renderBoard)
level.on('after:update:rules', renderRules)

window.addEventListener('keyup', event => {
  const keyDirections = { ArrowUp: 'up', ArrowDown: 'down', ArrowLeft: 'left', ArrowRight: 'right' }
  if (keyDirections[event.key]) {
    level.move(keyDirections[event.key])
  }

  if (event.key === 'z') {
    level.undo()
  }
})

As for renderBoard we simply loop through the board and render the blocks on a CSS grid element, nothing special here.

For the game assets, I scraped the GIFs from the official wiki and named them after their corresponding words. While this is sufficient for experiments like this, it is important to note that using copyrighted material without permission could result in infringement issues if you plan to publish or distribute this.

Rules

The hardest part is detecting the rules of the game, since there are so many possible combinations to consider:

• Rules can appear both vertically and horizontally
• We must detect both rules between nouns and properties, as well as subject complements
• "BABA AND ROCK AND WATER IS PUSH" makes all Baba, Rock, and Water blocks pushable
• "BABA IS YOU AND PUSH" makes Baba controllable and pushable.
• "BABA AND ROCK IS PUSH AND MELT" makes... you guessed it

We want to encapsulate all this complexity in one function so we don't need to deal with all these rules elsewhere.

So if you have rules like "BABA IS WATER" and "BABA AND ROCK IS PUSH AND HOT", the method "updateRules" should create the following four rules:

["BABA IS PUSH", "ROCK IS PUSH", "BABA IS HOT", "ROCK IS HOT"]

as well as the following complement: ["BABA", "WATER"]

To begin, we start by finding all noun text blocks, as these are the starting points.

class Level {
  updateRules() {
    // this rule is always present
    const rules = [['TEXT', 'IS', 'PUSH']]
    const complements = []

    // rules always start with nouns, so let's collect all:
    const nounTextBlocks = this.getBlocksFor('text')
      .filter(block => block.ref.type === 'noun')

    function addRule(block, axis) {
      // ...
    }

    // check both horizontally and vertically
    for (const textBlock of nounTextBlocks) {
      addRule(textBlock, 'row')
      addRule(textBlock, 'cell')
    }

    // remove any duplicates using https://github.com/MZanggl/flooent
    this.rules = unique(rules, rule => rule.join(' '))
    this.complements = complements
  }
}

This code provides a solid starting point. For each noun found, the "addRule" function is called for both the horizontal and vertical axes. Now, let's dive into how the "addRule" function works.

Consider the rule "BABA AND ROCK IS PUSH AND WATER". We can split this into two parts: the subject "BABA AND ROCK" and the predicate "PUSH AND WATER". The key here is to identify the "IS" operator as that's where the split happens!

The "subject" side should not contain any properties, as "BABA AND PUSH IS ..." would not make sense. We begin by collecting all adjacent text blocks that fit the sequence:

function addRule(block, axis) {
  const ruleBlocks = [block]
  let position = { ...block.position }
  const subjectSequence = [['noun'], ['operator']]
  const predicateSequence = [['property', 'noun'], ['operator']]
  let indexOfIsOperator = -1

  // loop and add blocks to "ruleBlocks" until the next cell is invalid
  while(true) {
    // increment the position on the x or y axis and find a text block there
    position[axis]++
    const nextTextBlock = this.board[position.row]?.[position.cell]?.find(block => block.id === 'TEXT')
    if (!nextTextBlock) break

    if (nextTextBlock.ref.id === 'IS') {
      // disallow multiple IS operators in a single rule
      if (indexOfIsOperator >= 0) break
      indexOfIsOperator = ruleBlocks.length
    } else {
      // check if the sequence matches to 
      // avoid bogus rules like "BABA ROCK IS" or "BABA AND IS"
      const parity = indexOfIsOperator === -1 ? subjectSequence : predicateSequence
      const remainder = ruleBlocks.length % 2
      if (!parity[remainder].includes(nextTextBlock.ref.type)) break
    }

    ruleBlocks.push(nextTextBlock)
  }
  // ... quick interruption
}

We now have a ruleBlocks array that contains valid text blocks to make up a rule. However, we still need to handle cases such as "BABA AND ROCK IS PUSH" and detect complements/transformations like "BABA IS ROCK".

To achieve this, we can simply discard the AND operators, split the array into the "subject side" and "predicate side", and then cross join both sides.

To split the array at the position of "IS," we can use the "point" API provided by flooent.

const [subjectBlocks, predicateBlocks] = point(ruleBlocks, indexOfIsOperator).split()
      
// we expect every operator except IS to be AND, so we can just discard them
const discardAND = block => block.ref.id !== 'AND'

// cross join - if one side is empty, nothing gets added
for (const subjectBlock of subjectBlocks.filter(discardAND)) {
  for (const predicateBlock of predicateBlocks.filter(discardAND)) {
    // subject block is always a noun, if predicate block is also
    // a noun, it goes to the complements, otherwise, it's a rule
    if (predicateBlock.ref.type === 'noun') {
      complements.push([subjectBlock.ref, predicateBlock.ref])
    } else {
      rules.push([subjectBlock.ref.id, "IS", predicateBlock.ref.id])
    }
  }
}

Conclusion

And with that, we have completed the basic integration of "Baba is You"! Although I haven't provided the full solution in this article, I hope this has provided a solid foundation for readers to piece together the presented code and potentially extend it with more advanced mechanics.

However, it's worth noting that the real game is both affordable and easily accessible, with the added bonus of including a level editor. Therefore, unless your goal is purely for learning and experimentation purposes, it may not make much sense to recreate the game from scratch. Regardless, I hope this article has provided some insight into the game's mechanics and how they can be implemented using JavaScript.

Webpack

File structure

We want to create all our frontend JavaScript and Vue files inside resources/assets/js. Webpack will transpile these and place them inside public/js. Let's create the necessary directory and file

mkdir resources/assets/js -p
touch resources/assets/js/main.js

// resources/assets/js/main.js

const test = 1
console.log(test)

Get Webpack Rolling

People who come from a Laravel background might be familiar with Laravel-Mix. The good thing is that we can use Laravel Mix for our Adonis project as well. It takes away much of the configuration hell of webpack and is great for the 80/20 use case. Start by installing the dependency and copy webpack.mix.js to the root directory of the project.

npm install laravel-mix --save
cp node_modules/laravel-mix/setup/webpack.mix.js .

webpack.mix.js is where all our configuration takes place. Let's configure it

// webpack.mix.js

let mix = require('laravel-mix');

// setting the public directory to public (this is where the mix-manifest.json gets created)
mix.setPublicPath('public')
// transpiling, babelling, minifying and creating the public/js/main.js out of our assets
    .js('resources/assets/js/main.js', 'public/js')



// aliases so instead of e.g. '../../components/test' we can import files like '@/components/test'
mix.webpackConfig({
    resolve: {
        alias: {
            "@": path.resolve(
                __dirname,
                "resources/assets/js"
            ),
            "@sass": path.resolve(
                __dirname,
                "resources/assets/sass"
            ),
        }
    }
 });

Also, be sure to remove the existing example to avoid crashes

mix.js('src/app.js', 'dist/').sass('src/app.scss', 'dist/');

Adding the necessary scripts

Let's add some scripts to our package.json that let us transpile our assets. Add the following lines inside scripts.

// package.json

"assets-dev": "node node_modules/cross-env/dist/bin/cross-env.js NODE_ENV=development webpack --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
"assets-watch": "node node_modules/cross-env/dist/bin/cross-env.js NODE_ENV=development webpack --watch --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
"assets-hot": "node node_modules/cross-env/dist/bin/cross-env.js NODE_ENV=development webpack-dev-server --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
"assets-production": "node node_modules/cross-env/dist/bin/cross-env.js NODE_ENV=production webpack --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"

We can execute npm run assets-watch to keep a watch over our files during development. Running the command should create two files: public/mix-manifest.json and public/js/main.js. It is best to gitignore these generated files as they can cause a lot of merge conflicts when working in teams...

Routing

Since we are building a SPA, Adonis should only handle routes that are prefixed with /api. All other routes will get forwarded to vue, which will then take care of the routing on the client side. Go inside start/routes.js and add the snippet below to it

// start/routes.js

// all api routes (for real endpoints make sure to use controllers)
Route.get("hello", () => {
    return { greeting: "Hello from the backend" };
}).prefix("api")
Route.post("post-example", () => {
    return { greeting: "Nice post!" };
}).prefix("api")

// This has to be the last route
Route.any('*', ({view}) =>  view.render('app'))

Let's take a look at this line: Route.any('*', ({view}) => view.render('app'))

The asterisk means everything that has not been declared before. Therefore it is crucial that this is the last route to be declared.

The argument inside view.render app is the starting point for our SPA, where we will load the main.js file we created earlier. Adonis uses the Edge template engine which is quite similar to blade. Let's create our view

touch resources/views/app.edge

// resources/views/app.edge

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Adonis & Vue App</title>
</head>
<body>
    <div id="app"></div>
    {{ script('/js/main.js') }}
</body>
</html>

The global script function looks for files inside resources/assets and automatically creates the script tag for us.

Vue Setup

Let's install vue and vue router

npm install vue vue-router --save-dev

And initialize vue in resources/assets/js/main.js

// resources/assets/js/main.js

import Vue from 'vue'
import router from './router'
import App from '@/components/layout/App'

Vue.config.productionTip = false


new Vue({
  el: '#app',
  router,
  components: { App },
  template: '<App/>'
})

In order to make this work we have to create App.vue. All layout related things go here, we just keep it super simple for now and just include the router.

mkdir resources/assets/js/components/layout -p
touch resources/assets/js/components/layout/App.vue

// /resources/assets/js/components/layout/App.vue

<template>
    <router-view></router-view>
</template>

<script>
export default {
  name: 'App'
}
</script>

We also have to create the client side router configuration

mkdir resources/assets/js/router
touch resources/assets/js/router/index.js

// resources/assets/js/router/index.js

import Vue from 'vue'
import Router from 'vue-router'

Vue.use(Router)

export default new Router({
    mode: 'history', // use HTML5 history instead of hashes
    routes: [
        // all routes
    ]
})

Next, let's create two test components inside resources/assets/js/components to test the router.

touch resources/assets/js/components/Index.vue
touch resources/assets/js/components/About.vue

// resources/assets/js/components/Index.vue

<template>
    <div>
        <h2>Index</h2>
        <router-link to="/about">To About page</router-link>
    </div>
</template>

<script>
export default {
    name: 'Index',
}
</script>

And the second one

// /resources/assets/js/components/About.vue

<template>
    <div>
        <h2>About</h2>
        <router-link to="/">back To index page</router-link>
    </div>
</template>

<script>
export default {
    name: 'About',
}
</script>

The index component has a link redirecting to the about page and vice versa. Let's go back to our router configuration and add the two components to the routes.

// resources/assets/js/router/index.js

// ... other imports
import Index from '@/components/Index'
import About from '@/components/About'

export default new Router({
    // ... other settings
    routes: [
        {
            path: '/',
            name: 'Index',
            component: Index
        },
        {
            path: '/about',
            name: 'About',
            component: About
        },
    ]
})

Launch

Let's launch our application and see what we've got. Be sure to have npm run assets-watch running, then launch the Adonis server using

adonis serve --dev

By default Adonis uses port 3333, so head over to localhost:3333 and you should be able to navigate between the index and about page. Try going to localhost:3333/api/hello and you should get the following response in JSON: { greeting: "Nice post!" }.

Bonus

We are just about done, there are just a few minor things we need to do to get everything working smoothly:

• CSRF protection
• cache busting
• deployment (Heroku)

CSRF protection

Since we are not using stateless (JWT) authentication, we have to secure our POST, PUT and DELETE requests using CSRF protection. Let's try to fetch the POST route we created earlier. You can do this from the devtools.

fetch('/api/post-example', { method: 'post' })

The response will be somthing like POST http://127.0.0.1:3333/api/post-example 403 (Forbidden) since we have not added the CSRF token yet. Adonis saves this token in the cookies, so let's install a npm module to help us retrieving it.

npm install browser-cookies --save

To install npm modules I recommend shutting down the Adonis server first.

Next, add the following code to main.js

// resources/assets/js/main.js

// ... other code

import cookies from 'browser-cookies';

(async () => {
    const csrf = cookies.get('XSRF-TOKEN')
    const response = await fetch('/api/post-example', {
        method: 'post',
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'x-xsrf-token': csrf,
        },
    });

    const body = await response.json()

    console.log(body)
})()

This should give us the desired result in the console! I recommend extracting this into a module. Of course you can also use a library like axios instead.

Cache Busting

Cache Busting is a way to make sure that our visitors always get the latest assets we serve. To enable it, start by adding the following code to webpack.mix.js

// webpack.mix.js

mix.version()

If you restart npm run assets-watch, you should see a change inside mix-manifest.json

// public/mix-manifest.json

{
    "/js/main.js": "/js/main.js?id=e8f10cde10741ed1abfc"
}

Whenever we make changes to main.js the hash will change. Now we have to create a hook so we can read this JSON file in our view.

touch start/hooks.js

const { hooks } = require('@adonisjs/ignitor')
const Helpers = use('Helpers')

const mixManifest = require(Helpers.publicPath('mix-manifest.json'))

hooks.after.providersBooted(async () => {
    const View = use('View')
    View.global('versionjs', (filename) => {
        filename = `/js/${filename}.js`
        if (!mixManifest.hasOwnProperty(filename)) {
            throw new Error('Could not find asset for versioning' + filename)
        }

        return mixManifest[filename]
    })

    View.global('versioncss', (filename) => {
        filename = `/css/${filename}.css`
        if (!mixManifest.hasOwnProperty(filename)) {
            throw new Error('Could not find asset for versioning' + filename)
        }

        return mixManifest[filename]
    })
})

This will create two global methods we can use in our view. Go to resources/assets/views/app.edge and replace

{{ script('/js/main.js') }}

with

{{ script(versionjs('main')) }}

And that's all there is to cache busting.

Deployment

There is already an article on deploying Adonis apps to Heroku. Because we are having our assets on the same project though, we have to add one or two things to make the deployment run smoothly. Add the following code under scripts inside package.json

// package.json

"heroku-postbuild": "npm run assets-production"

This tells Heroku to transpile our assets during deployment. If you are not using Heroku, other services probably offer similar solutions.

In case the deployment fails...

You might have to configure your Heroku app to also install dev dependencies. You can configure it by executing the following command

heroku config:set NPM_CONFIG_PRODUCTION=false YARN_PRODUCTION=false

Alternatively you can set the configurations on the Heroku website directly.

And that's all there is to it.

To skip all the setting up you can simply clone the demo repo with

adonis new application-name --blueprint=MZanggl/adonis-vue-demo

So a script on the frontend simply imports a function from the backend and calls it to get the user.

Not mindblowing? Okay, how about this?

// FRONTEND
// resources/js/main.js

import { getUser } from '@/app/Actions/users.php'

getUser(1).then(user => {
  document.getElementById('app').innerHTML = JSON.stringify(user)
})

In case you missed it, pay close attention to this line:

import { getUser } from '@/app/Actions/users.php'

Let's zoom in some more: '@/app/Actions/users.php'. And some more .php.

Yes, the approach is not limited to Node.js but can work with possibly any backend language.

So what's going on? Obviously we got rid of the API layer, but how?

Well, honestly, we haven't, we just swept it under the carpet. That means when you call getUser it will still perform an ajax request to the server. There will still be an api route on the backend. But all of that boilerplate and dealing with HTTP is poof gone.

No more fetch requests to the backend, no more setting up API routes, no need for controllers. That means if you want to find out what the ajax request is doing, you no longer have to track down the routes file, go to the controller which again just goes to some service file. Just (ctrl/cmd) + click on the function. It's seamless.

How it works

It's surprisingly simple. A roughly 10 line webpack loader (could be rollup, TS, etc.) on the frontend that intercepts module resolution for files from the backend. Instead of importing the backend code, it will import a function that performs an HTTP request for you pointing to the correct route. At the same time, the backend will automatically create the JSON API for all files inside the "actions" folder. So you can still use the JSON API are you in need of a mobile app for example.

Check it out here if you want to give it a try: https://github.com/MZanggl/byebye-api-prototype.

This is obviously still a prototype. But you might have seen something similar already in frameworks like Blitzjs.

I also prepared an example with adonis.js on the backend and vue.js on the frontend to give a more real world example that also covers some more use cases like auth: https://github.com/MZanggl/adonis-vue-without-api.

This example does things a little differently. The backend generates the routes into a file that the frontend then makes use of for its fetch requests. This way, you don't need to write a language parser for each backend language and there is a single source of truth.

The Bad

The good thing about IDs is that they don't change. This is not true for text. See for example:

• a GitHub repository: https://github.com/MZanggl/promistate
• an article on dev.to: https://dev.to/michi/tailwind-css-for-skeptics-interactive-tailwind-css-tutorial-1h15

They both contain two slugs. The username and the name of the repository/article.

But what happens if you change your username?

Well, GitHub has an entire article about the side effects: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/changing-your-github-username

It says that the old username will be made available again for others to use. It goes on to say:

" Web links to your existing repositories will continue to work. ... If the new owner of your old username creates a repository with the same name as your repository, that will override > the redirect entry and your redirect will stop working. "

This, of course, has the potential to be exploited. If you forget to update only one link to a repo of yours in a blog post, package.json, or elsewhere, somebody can now claim that username, create a repository under the same name, and cause some pretty hefty damage under your name.

dev.to also allows changing the username/title but leaves you in the dark with what will happen to the old handle and all the links associated with it.

An alternative way to use slugs is the way Reddit does. See the link for the following article: https://www.reddit.com/r/javascript/comments/i1zwek/nextjs_serverside_route_authentication_using/ You can actually change the title in the link, and it would still work, as it still contains the ID.

The Ugly

Slugs might work great for English and languages that use the Roman script but look what happens when I copy the link from a product page from the Japanese Amazon store:

https://www.amazon.co.jp/Nintendo-Switch-%E3%83%8B%E3%83%B3%E3%83%86%E3%83%B3%E3%83%89%E3%83%BC%E3%82%B9%E3%82%A4%E3%83%83%E3%83%81-%E3%83%8D%E3%82%AA%E3%83%B3%E3%83%AC%E3%83%83%E3%83%89%E3%80%91-%E3%83%8B%E3%83%B3%E3%83%86%E3%83%B3%E3%83%89%E3%83%BCe%E3%82%B7%E3%83%A7%E3%83%83%E3%83%97%E3%81%A7%E3%81%A4%E3%81%8B%E3%81%88%E3%82%8B%E3%83%8B%E3%83%B3%E3%83%86%E3%83%B3%E3%83%89%E3%83%BC%E3%83%97%E3%83%AA%E3%83%9A%E3%82%A4%E3%83%89%E7%95%AA%E5%8F%B73000%E5%86%86%E5%88%86/dp/B07SVXHD1P/ref=sr_1_13?dchild=1&keywords=switch&qid=1596343204&sr=8-13

Now imagine sending such a link on an app like WhatsApp where you just have a little space. It's quite the opposite of human-readable, how ironic.

Wait, but why is this happening in the first place?

An explanation as to why the browser returns you this encoded version of the link can be found here.

Let's confirm what is said by checking the request on the Amazon site's GET request:

I'm not an expert on this topic, but the reason why URI, instead of IRI, is still being used to this day might be due to exploits like the IDN homograph attack.

While slugs do enhance UX, oftentimes it's only minor enhancement. We already have open graph to display title, description, image, etc. when sharing links. Sites like twitter use URL shorteners anyways. Referencing sites on Reddit, blog posts, news articles, etc. usually don't show the raw link, but provide alternative text, etc.

Conclusion

Now, slugs are still great. But it's not as simple as adding one to your website and you are done (unless you have total control over the content...).

If you plan to implement slugs into your website, make sure you

• Educate your users about what happens when you change content that is part of a slug
• Only include URL-friendly characters

I guess the gist of this post is that just because something looks simple in tech, it often comes with a lot of added complexity, and it's never as simple as "just doing this one little thing". The YouTube video page works just fine with just an ID in the slug.

comparing varchar_field with false or 0

Imagine the following contrived example

function normalizeEmail(email) {
    if (!validate(email)) {
        return false
    }

    return normalize(email)
}

// somewhere in the code
await User.where('email', normalizeEmail(email)).first()

The imaginary ORM would execute the query select * from users where email = <prepared value> LIMIT 1

If the validation inside normalizeEmail was successful, the query would be select * from users where email = 'normalized.email@test.com' LIMIT 1.

If the validation was not successful, the query would be select * from users where email = false LIMIT 1.

Now go ahead and run something like select * from users where <varchar field> = false in your database system.

Since the fields are not comparable, MySQL will convert one to the other, make them match and return you all users. Our ORM will simply pick the first user and continue the logic with that. 😬 Pretty dangerous.

The same happens with field = 0

insert on duplicate key update creates primary key holes

Imagine we have a table statistics with the columns id(AI), fkid, title.

INSERT INTO statistics (fkid, title) VALUES (1, 'first');

This will insert a new record with the id 1. Let's imagine there is some batch which always inserts or updates the title. It might execute the following queries over some time:

INSERT INTO statistics (fkid, title) VALUES (1, 'second') ON DUPLICATE KEY UPDATE title = 'second';
INSERT INTO statistics (fkid, title) VALUES (1, 'third') ON DUPLICATE KEY UPDATE title = 'third';
INSERT INTO statistics (fkid, title) VALUES (1, 'fourth') ON DUPLICATE KEY UPDATE title = 'fourth';

Finally we want to insert a record with a new fkid.

INSERT INTO statistics (fkid, title) VALUES (100, 'first') ON DUPLICATE KEY UPDATE title = 'first';

This inserts a new record in the table, but guess what the id is? You'd might expect it to be 2, but in reality, everytime insert on duplicate key update failed to insert and processed the update, it incremented the auto increment internally. That means the id of this record would be 5.

It's not too important that the IDs are really sequential, but you might wonder what's the cause of it.

Read more about it: https://stackoverflow.com/questions/38347110/prevent-innodb-auto-increment-on-duplicate-key

int(2) is not what you think it means

The length on INTs have no real meaning in MySQL, you can still insert values like 9999999. They only restrict how many characters should be displayed in the command line client. 🤨

Read more about it: https://stackoverflow.com/questions/5634104/what-is-the-size-of-column-of-int11-in-mysql-in-bytes

What's the fix?

You can turn a string into both its precomposed as well as decomposed representation using string.normalize.

const decomposed = [...'Jalapeño'.normalize('NFD')]
// (9) ['J', 'a', 'l', 'a', 'p', 'e', 'n', '̃', 'o']

const precomposedAgain = [...decomposed.join('').normalize()]
// (8) ['J', 'a', 'l', 'a', 'p', 'e', 'ñ', 'o']

Setup

This article assumes you already have a backend that provides a CSRF token solution.

There is actually more than one way to set this up, depending on what your backend's CSRF token solution offers, I will introduce two approaches.

Approach 1: A cookie

1. The client initializes CSRF protection by calling an endpoint on the API server that sets a cookie with httpOnly set to false holding the CSRF token
2. For subsequent API requests, the client grabs the cookie from document.cookie, and passes it to the request (usually in the header under "X-CSRF-TOKEN")
3. With each API request, the API server updates the cookie with a fresh token.

For the API server to place a cookie that the client can read, the SPA and the API server have to be on the same domain.

Approach 2: An API endpoint

1. The backend needs to provide an API endpoint (e.g. /csrf) that returns a CSRF token
2. The client calls this endpoint to get their token
3. The CSRF token is then passed into each subsequent API request similar to approach 1

This approach works also if SPA and API are on a different domain.

🤔 When should the client get a new CSRF token?

There are a few options:

• Grab a new token each time before making a request by calling "/csrf" again
• Make the backend return a new token as part of every API response, and make the client use it for the next request

🤔 How is the CSRF token endpoint secured?

• The API server must have CORS set to allow only trusted sites like the SPA. This is to prevent third-party AJAX requests from getting hold of a CSRF token that works for you.
• The endpoint's response must not be JSON hijackable. { token: 'xxx' } will do.

🤔 Can an attacker not just call the "/csrf" endpoint from a server, where CORS doesn't apply?

This question was actually covered in my previous article, not for API endpoints, but for grabbing a CSRF token from a form in the HTML.

But it's the same story: CSRF tokens are typically bound to the user's session, so your CSRF tokens won't work for me.

Finally, depending on the solution you pick, and your backend setup, you might have to add logic to handle token expiry. For example, by redirecting to the login page when receiving a 401 or 419 status.

Next time, let's see how auth cookies should be secured.

What is happening in the code? There is a Database class used to save things into the database and a UserService class used to create users. The users are going to be saved in the database, so when we create a new user, we new up an instance of Database. In other words, UserService is dependent on Database. Or, Database is a dependency of UserService.

And here comes the problem. What if we were to write tests to check the part // do a lot of validation etc.. We need to write a total of 10 tests for various scenarios. In all of these tests, do we really want to insert users into the database? I don't think so. We don't even care about this part of the code. So it would be nice if it was possible to swap out the database with a fake one when running tests.

Dependency Injection

Enter dependency injection. It sounds very fancy, but in reality is super simple. Rather than newing up the Database instance inside the "create" method, we inject it into the UserService like this.

class Database {
    insert(table, attributes) {
        // inserts record in database
        const isSuccessful = true
        return isSuccessful
    }
}

class UserService {
    constructor(db) {
        this.db = db
    }

    create(user) {
        return this.db.insert('users', user)
    }
}

const db = new Database
const userService = new UserService(db)

const result = userService.create({ id: 1})
console.log(result)

And the test could look something like this

class TestableDatabase {
    insert() {
        return true
    }
}


const db = new TestableDatabase
const userService = new UserService(db)

But of course, I hear what you saying. While we made the code testable, the API suffered from it. It's annoying to always pass in an instance of Database.

Inversion of Control

Enter Inversion of Control. Its job is to resolve dependencies for you.

It looks like this: At the start of the app you bind the instantiation to a key and use that later at any point.

Before we check out the code of our IoC container (also called service container), let's look at the usage first.

ioc.bind('userService', () => new UserService(new Database))

Now you can use ioc.use at any point in your app to access the userService.

ioc.use('userService').create({ id: 1})

Whenever you call ioc.use('userService'), it will create a new instance of UserService, basically executing the callback of the second function. If you prefer to always access the same instance, use app.singleton instead of app.bind.

ioc.singleton('userService', () => new UserService(new Database))

ioc.use('userService').create({ id: 1})

Implementation of ioc

global.ioc = {
    container: new Map,
    bind(key, callback) {
        this.container.set(key, {callback, singleton: false})
    },
    singleton(key, callback) {
        this.container.set(key, {callback, singleton: true})
    },
    use(key) {
        const item = this.container.get(key)

        if (!item) {
            throw new Error('item not in ioc container')
        }
        
        if (item.singleton && !item.instance) {
            item.instance = item.callback()
        }

        return item.singleton ? item.instance : item.callback()
    },
}

That's not a lot of code at all! so the methods bind and singleton just store the key and callback inside a map and with the use method, we get what we want from the container again. We also make ioc a global variable so it is accessible from anywhere.

But where do we put all those ioc bindings?

Service Providers

Enter the service provider. Another fancy term simply meaning "This is where we bind our stuff in the service container". This can be as simple as having

// providers/AppProvider.js

function register() {
    ioc.singleton('userService', () => new UserService(new Database))
}

module.exports = { register }

The register method of the provider is then simply executed at the start of your app.

Testing

How do we test it now?

Well, in our test we can simply override the userService in the service container.

class TestableDatabase {
    create() {
        return true
    }
}


ioc.singleton('userService', () => new UserService(new TestableDatabase))

ioc.use('userService').create({id: 1})

This works, but there is the problem that if you have tests that require the actual database in the userService, these might also receive the TeastableDatabase now. Let's create a fake and restore method on the ioc object instead. We also have to alter our use method a little

global.ioc = {
    container: new Map,
    fakes: new Map,
    bind(key, callback) {
        this.container.set(key, {callback, singleton: false})
    },
    singleton(key, callback) {
        this.container.set(key, {callback, singleton: true})
    },
    fake(key, callback) {
        const item = this.container.get(key)
        
        if (!item) {
            throw new Error('item not in ioc container')
        }

        this.fakes.set(key, {callback, singleton: item.singleton})
    },
    restore(key) {
        this.fakes.delete(key)
    },
    use(key) {
        let item = this.container.get(key)
        
        if (!item) {
            throw new Error('item not in ioc container')
        }

        if (this.fakes.has(key)) {
            item = this.fakes.get(key)
        }

        if (item.singleton && !item.instance) {
            item.instance = item.callback()
        }

        return item.singleton ? item.instance : item.callback()
    },
}

And let's update our test

class TestableDatabase {
    insert() {
        return true
    }
}


ioc.fake('userService', () => new UserService(new TestableDatabase))

ioc.use('userService').create({id: 1})

ioc.restore('userService')

Other use cases

Avoids useless abstractions

This example is taken from the Adonis documentation.

Some objects you want to instantiate one time and then use repeatedly. You usually do this by having a separate file just to handle the singleton.

const knex = require('knex')

const connection = knex({
  client: 'mysql',
  connection: {}
})

module.exports = connection

With the IoC container this abstraction is not necessary, thus making the code base cleaner.

Avoids relative require

Imagine you are somewhere very deep inside the file app/controllers/auth/UserController.js and want to require the file app/apis/GitHub.js. How do you do that normally?

const GitHub = require('../../apis/GitHub')

How about we add this to the service container instead?

// providers/AppProvider.js

ioc.bind('API/GitHub', () => require('../app/apis/GitHub')

and now we can use it like this from anywhere

ioc.use('API/GitHub')

Since it is annoying to do that for every file, let's simply add a method to require files from the root directory.

Add the following code to the end of the ioc.use method and remove the exception throw when the key was not found.

global.ioc = {
// ...
    use(key) {
        // ...
        return require(path.join(rootPath, namespace))
    }
}

Now we can access the GitHub service using

ioc.use('apis/GitHub')

But with that the ioc container must live in the root of the directory. Let's extract the IoC container out and make a factory out of it. The end result is

//lib/ioc.js

module.exports = function createIoC(rootPath) {
    return {
        container: new Map,
        fakes: new Map,
        bind(key, callback) {
            this.container.set(key, {callback, singleton: false})
        },
        singleton(key, callback) {
            this.container.set(key, {callback, singleton: true})
        },
        fake(key, callback) {
            const item = this.container.get(key)
            
            if (!item) {
                throw new Error('item not in ioc container')
            }
    
            this.fakes.set(key, {callback, singleton: item.singleton})
        },
        restore(key) {
            this.fakes.delete(key)
        },
        use(namespace) {
            let item = this.container.get(namespace)
            
            if (item) {
                if (this.fakes.has(namespace)) {
                    item = this.fakes.get(namespace)
                }
        
                if (item.singleton && !item.instance) {
                    item.instance = item.callback()
                }
        
                return item.singleton ? item.instance : item.callback()
            }

            return require(path.join(rootPath, namespace))
        }
    }
}

We wrapped the object inside the function createIoC that expects the root path to be passed in. The "require" method now returns the following return require(rootPath + '/' + path).

And inside index.js we now have to create the container like this

global.ioc = require('./lib/ioc')(__dirname)

And that's it for the basics of IoC! I put the code on GitHub where you can check it out again. I also added some tests to it and made it possible to fake root requires as well.

The end result was a mix of multiple approaches and things that I have not even thought of before. And it only took an hour of writing to clear my brain that has been foggy for days now.

One more thing I came to understand:

I can type pretty fast, but I realized that typing fast was paradoxically slowing me down. My thoughts couldn't catch up. I couldn't keep the "conversation" going. So try slowing down when you feel the same way.

Unfortunately, that also means that detecting the end of a chain only works for asynchronous operations. I mean, theoretically, you could do it with synchronous code but you would have to use the await keyword, which might throw some off. Apart from this hack, there is no way in JavaScript currently to detect the end of a chain for synchronous operations.

So let's look at the first implementation with the explicit .end() method. Or jump straight to the solution.

Here is a possible API:

class Client {
  as(user) {
    this.user = user
    return this
  }

  get(endpoint) {
    this.endpoint = endpoint
    return this
  }

  async end() {
    return fetch(this.endpoint, { headers: { ... } })
  }
}

Solution

And here is the little trick to achieve it without an explicit end() method.

class Client {
  as(user) {
    this.user = user
    return this
  }

  get(endpoint) {
    this.endpoint = endpoint
    return this
  }

  async then(resolve, reject) {
    resolve(fetch(this.endpoint, { headers: { ... } }))
  }
}

So all we needed to do was switching out "end()" with "then()" and instead of returning the result, we pass it through the resolve callback.

If you have worked with promises, you are probably already familiar with the word then. And if you ever used new Promise((resolve, reject) => ... this syntax will look weirdly familiar.

Congratulations. You have just successfully duck-typed A+ promises.

A promise is nothing more than a "thenable" (an object with a then() method), which conforms to the specs. And await is simply a wrapper around promises to provide cleaner, concise syntax.

So in summary, to achieve an async fluent API, all you need to do is define a "then" method which either resolves or rejects any value through the two given arguments.

Note: To be fair, there are some subtleties that we've missed with this simple approach. For example, calling "then" on a promise multiple times will only execute it the first time it gets called. You can achieve the same here by keeping a reference to the promise on the class instance when "then" is called. Subsequent calls would then simply return that reference.

To help us achieve the goal and add many other useful methods at the same time, let's integrate lodash.

In order to pluck using lodash you use lodash's own map method. If you pass a string instead of a function as the second argument, that string becomes the key it will pluck.

_.map(locations, 'city')

So here are the tests

const expect = require('chai').expect
const { proxy } = require('../src/roxy')

describe('proxy', function() {
    it('should be able to access Array.prototype methods', function() {
        const numbers = proxy([1, 2, 3])
        numbers.copyWithin(0, 1, 2) // lodash doesn't have `copyWithin`
        expect(numbers).to.deep.equal([ 2, 2, 3 ])
    })

    it('should pluck using lodash method', function() {
        const numbers = proxy([
            { id: 1 },
            { id: 2 },
            { id: 3 },
        ])

        const result = numbers.map('id')
        expect(result).to.deep.equal([ 1, 2, 3 ])
    })
})

That's pretty cool. We got rid of the new keyword and classes altogether. Let's check out roxy.js.

// let's only load the lodash methods we need
var lodashArray = require('lodash/array')
var lodashCollection = require('lodash/collection')

const proxySymbol = Symbol('isProxy')

function _transformResult(result) {
    if (Array.isArray(result) && !result[proxySymbol]) {
        return proxy(result)
    }
    return result
}

const libraryList = [lodashCollection, lodashArray]

function proxy(array) {
    const handler = {
        get: function get(target, prop) {
            const library = libraryList.find(library => typeof library[prop] === 'function')
            if (library) {
                return function(...args) {
                    const result = library[prop](this, ...args)
                    return _transformResult(result)
                }
            }

            if (typeof target[prop] !== 'undefined') {
                return target[prop]
            }

            if (prop === proxySymbol) {
                return true
            }
        }
    }
    
    return new Proxy(array, handler)
}

module.exports = {
    proxy,
}

Proxies are exactly what their name suggest. We could also say it is a gateway to the actual array. But the gateway is guarded by so called traps. In this case, whenever you access a property on the array, it will not actually access it, but it will get trapped in the get method of our handler, so let's go through it step by step to understand it.

const library = libraryList.find(library => typeof library[prop] === 'function')
if (library) {
    return function(...args) {
        const result = library[prop](this, ...args)
        return _transformResult(result)
    }
}

First, we check if the method is either inside lodash collections or lodash arrays.

If you access array.map it will find it inside lodashCollection and return a new function. The function already knows at that point that library[prop] will be lodashCollection.map.

Then, when you execute the function like this array.map('id'), it will take the arguments you passed and executes the lodash function together with the actual array as the first argument.

With _transformResult we will proxy the result again in case it is a normal array. This allows for better chaining.

if (typeof target[prop] !== 'undefined') {
    return target[prop]
}

Next, we want to check if the method is an existing property of the array and simply return it. This would be the case for accessing the length property or methods like copyWithin that don't exist in lodash.

if (prop === proxySymbol) {
    return true
}

This lets us know whether an array is a roxy instance or not. In _transformResult when we access result[proxySymbol] and result is already a roxy instance, it would get trapped in the get method and would return true at this point if (prop === proxySymbol). So in case the returned array is already a roxy instance, no need to proxy it again.

Check out the part of _transformResult again:

if (Array.isArray(result) && !result[proxySymbol]) {
    return proxy(result)
}
return result

We can check if _transformResult works by writing another test

it('should be able to chain lodash methods', function() {
    const locations = proxy([
        { location: {city: 1 } },
        { location: {city: 2 } },
        { location: {city: 3 } },
    ])

    const result = locations.map('location').map('city')
    expect(result).to.deep.equal([ 1, 2, 3 ])
})

The same way you can now use lodash's map method, you should be able to use a bunch more like chunk, keyBy, shuffle and so on.

Of course you don't have to use lodash. You can do something similar with any array library. But there is probably not a single library that would fulfill all your expecations. So let's also add a method to create custom macros.

The test

const { proxy, macro } = require('../src/roxy')

// ...

it('can use macros', function() {
    macro('stringify', (array, prepend) => prepend + JSON.stringify(array))

    const numbers = proxy([1, 2])
    const result = numbers.stringify('array: ')
    expect(result).to.equal('array: [1,2]')
})

For the implementation, we only have to do a couple things.

const macroMap = {}
const libraryList = [lodashCollection, lodashArray, macroMap]

function macro(name, fn) {
    macroMap[name] = fn
}

// ...

module.exports = {
    proxy,
    macro,
}

And that's all there is to it!

Conclusion

Proxies offer a wide range of new possibilities to explore. In fact the next major version of vue will use proxies for its reactivity system. This tutorial made only use of the get trap. There are actually many more like set, construct, has, etc. Check out the mdn references below to learn more about proxies.

References

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
• https://github.com/MZanggl/roxy
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol

Apply YANGI not only to code but to the product too

You might already apply the principle of YAGNI (you ain't gonna need it) to the code that you write, writing only what is essential and needed right now, and not things you might need in the future. We can take that same principle and apply it to the product we are building.

Say you are running dev.to. When people create blog posts they can add predefined tags to them. Now, say the predefined tags are not enough and dev.to wants its users to somehow be able to add completely new tags but only upon review.

There are two ways you could do this

The hard way:

• Let user add any tag and show warning that nonexisting tags will first be reviewed
• We now have to save the tag in the DB with a special "for review"-flag
• We also need a new UI on some form of CMS to go through these and review them
• We need to send an automated mail when a tag has been accepted/rejected

Or the simple way: When entering a tag, the tag suggestions already show a message that tags have rules and guidelines to follow. Simply extend this message to say: "To suggest new tags send us an email at yo@dev.to".

The problem with the first approach is that it has a bunch of dependencies like database, changes to the backend, even an admin panel. The second approach reuses something that already exists in the app, and only requires minimal changes on the UI. We might get to the first approach eventually, but we will know better what to build once we release a simple version of the core idea.

This leads us to the next point...

Work in small iterations

Like in the example above, think what is the simplest thing you can build. You don't want to spend 1 week on a feature that turns into 3 weeks because you suddenly run into all kinds of inconsistencies with dependencies. That can be quite exhausting. Think small, and you might not even need that perfect solution in the end. Once the core idea is out, you will have a better understanding of how your users actually use this feature and you can better judge how to go from here.

Another example would be working on a new website. Start with a feature, the core thing. No reason for a header, footer, special font or sidebar right away.

Most have 2 hours a week

Try to block out two hours a week. Maybe one hour on Sunday morning and one hour on Wednesday night.

This tip goes to Jeffrey Way in his podcast episode Focus on two hours, not two years

Define your goal for each session

Say you split your time up into two 1 hour sessions a week. When you start a session set a goal and focus! That means no social media, no videos, no news, no twitter, no kids, no games. Block out all distractions!

Don't get stuck on the little things

This goes hand in hand with the previous point. Focus on your goal. This is not the time to refactor some random file you stumbled upon, or to play with lint rules, or to fix a type issue in an open-source library you are using. If you do believe these are important, take a note and turn it into a separate session! You can host your project privately on GitLab/GitHub and use the issue tracker to keep track of everything that needs to be done.

Know when to break out of a problem chain

This tweet from Caleb Porzio tells it so nicely:

Knowing when to back out of a problem chain and re-evaluate the original problem.

What tools to choose

You don't need a fully dockerized scalable microservice architecture with GraphQL API and micro frontends with redux and TDD, BDD and DDD.

If you are productive with these tools, by no means go for it. Also, if that's exactly what you want to learn with this side project, again, go for it!

But if your goal is to build a product and the tech is just a way to help you get there, then you might want to choose a more high-level framework.

Coding, in the end, is kind of like building Lego's. Using a framework, you simply put together 64x64 instead of 4x4 pieces. They let you focus on actually building the product you set out to make and it doesn't keep you distracted on things like architecture, authentication, DB access etc.

On the backend there are some very nice "all-purpose" battery included frameworks like Rails (ruby), Laravel (PHP) or AdonisJs (javascript). I recommend reading the paragraph the menu is omakase from the rails doctrine.

To summarize it

• Work in small iterations
• Focus on 2 hours, not 2 years
• Define a goal for each session
• Don't get stuck on the little things
• Know when to break out of a problem chain
• Choose tools that help you get there faster

git amend

Sometimes you just miss committing something. Adding more changes to the latest commit was never easier. It doesn't even open vim for you to change the commit message, it just appends to the latest commit.

git config --global alias.amend "commit --amend --no-edit"

git update

While working on a feature branch, more than often, by the time you want to merge back into the main branch (develop/master), that main branch already has a few new commits. Keeping your local branch up to date will help avoiding big merge conflicts. I use this one daily.

git config --global alias.update "pull --rebase origin develop"

bonus

Adding "-n" when committing allows you to skip precommit hooks like linting. This is sometimes necessary when working with legacy code. The following alias at least makes you feel bad about it.

git config --global alias.commit-crime "commit -n"

Last but not least here is a handy alias to list all aliases. Let's name it "alias".

git config --global alias.alias "! git config --get-regexp ^alias\. | sed -e s/^alias\.// -e s/\ /\ =\ /"

The .yml file

If you haven't already, create the directories .github/workflows in the root of your repository. Inside, create a file "cd.yml".

To get the release info we will be using data passed in by GitHub which is available under the variable "github".

To see everything it contains, you can echo it out in your workflow:

- run: echo "${{ toJson(${{ github.event) }}"

And here is the content of the cd.yml file. I will not go through it line by line, instead, I added comments to each line explaining what is happening.

name: NPM publish CD workflow

on:
  release:
    # This specifies that the build will be triggered when we publish a release
    types: [published]

jobs:
  build:

    # Run on latest version of ubuntu
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
      with:
        # "ref" specifies the branch to check out.
        # "github.event.release.target_commitish" is a global variable and specifies the branch the release targeted
        ref: ${{ github.event.release.target_commitish }}
    # install Node.js
    - name: Use Node.js 12
      uses: actions/setup-node@v1
      with:
        node-version: 12
        # Specifies the registry, this field is required!
        registry-url: https://registry.npmjs.org/
    # clean install of your projects' deps. We use "npm ci" to avoid package lock changes
    - run: npm ci
    # set up git since we will later push to the repo
    - run: git config --global user.name "GitHub CD bot"
    - run: git config --global user.email "github-cd-bot@example.com"
    # upgrade npm version in package.json to the tag used in the release.
    - run: npm version ${{ github.event.release.tag_name }}
    # build the project
    - run: npm run build
    # run tests just in case
    - run: npm test
    # publish to NPM -> there is one caveat, continue reading for the fix
    - run: npm publish
      env:
        # Use a token to publish to NPM. See below for how to set it up
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
    # push the version changes to GitHub
    - run: git push
      env:
        # The secret is passed automatically. Nothing to configure.
        github-token: ${{ secrets.GITHUB_TOKEN }}

NPM auth token

We publish to NPM using a token NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}. But we still have to configure the "NPM_TOKEN" secret.

First, go to npm, in the settings go to "Auth Tokens", and click the button "Create New Token".

Copy the token and head over to the project settings of your GitHub repository. Go to "Secrets" and click "New Secret". Give it the name "NPM_TOKEN" and for the value, paste the token inside.

With the secret set up, GitHub will now be able to resolve ${{ secrets.NPM_TOKEN }} with the token from your GitHub secrets.

Fixing an NPM caveat

It already works at this point!

We can create a release with the tag 2.1.0 and target the "latest" branch. We can also create a release with the tag "1.3.4" targetting the "v1-latest" branch.

Make sure, when you create the release, to use a tag following semver. E.g. 2.0.0, v2.0.0, 2.0.0-beta.1, etc.

However, there is one caveat when publishing an old version.

You see, when you do npm install flooent it will actually do npm install flooent@latest behind the scenes. And when you do npm publish it will actually do npm publish --tag latest.

"latest" is a reserved tag for NPM. However, even though the project is already on version 2, publishing a fix for version 1 will make it the "latest" version. This means when somebody installs the package afterward, he will get version 1 instead of version 2. That's of course not what we want.

So to fix this, we have to specify a different tag when publishing. One way to do this is by adding a default publish tag to the v1 branch package.json:

"publishConfig": {
  "tag": "v1-latest"
}

But there's also another way. Remember the branch names I chose? "latest" and "v1-latest". Sounds just like tags we can use for NPM.

So instead of fiddling with package.json in each branch, all we have to do is go to our yaml file and replace

- run: npm publish

with

- run: npm publish --tag ${{ github.event.release.target_commitish }}

The reason I chose v1-latest over just v1 is that npm tags must not follow semver. Otherwise, NPM would not be able to distinguish a tag from a specific published version.

Setting up the different parts for CD was admittedly the hardest part to get right, but the resulting yaml file is actually quite small and straight forward.

Setting up CI

In this post, we will cover how to run tests automatically when pushing a change to a repository or creating/updating a PR.

To get started you need to create a .yml file in a specific directory. While you can do that through GitHub (under "Actions"), in this post we will set it up on our local. It's really simple.

In the root of your repository create the directories .github/workspaces.

mkdir .github
cd .github
mkdir workspaces
cd workspaces

GitHub Actions will pick up .yml files inside this directory. Let's create the file ci.yml.

Basically it goes like this:

• checkout the branch
• install node (on ubuntu)
• install the dependencies of your project and build it if necessary
• finally, run the tests

I added comments to almost every line explaining the setup.

# This workflow will do a clean install of node dependencies, build the source code and run tests
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: CI Pipeline

# trigger build when pushing, or when creating a pull request
on: [push, pull_request]

jobs:
  build:

    # run build on latest ubuntu
    runs-on: ubuntu-latest

    steps:
    # this will check out the current branch (https://github.com/actions/checkout#Push-a-commit-using-the-built-in-token)
    - uses: actions/checkout@v2
    # installing Node
    - name: Use Node.js 12.x
      uses: actions/setup-node@v1
      with:
        # this will use the latest Node 12 version
        node-version: 12.x
    # install dependencies using clean install to avoid package lock updates
    - run: npm ci
    # build the project if necessary
    - run: npm run build --if-present
    # finally run the tests
    - run: npm test

Note how we make use of other GitHub actions like actions/checkout@v2. Actions like these handle common tasks, and of course, you can create your own!

If you want to run tests across different versions of Node, you can specify a matrix. The script would look like this:

# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: Node.js CI

# trigger build when pushing, or when creating a pull request
on: [push, pull_request]

jobs:
  build:

    # run build on latest ubuntu
    runs-on: ubuntu-latest

    strategy:
      matrix:
        # Run build for both Node version 12 and version 14
        node-version: [12.x, 14.x]

    steps:
    # for checking out the branch (https://github.com/actions/checkout#Push-a-commit-using-the-built-in-token)
    - uses: actions/checkout@v2
    # installing Node
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        # this is regarding the matrix strategy specified above
        node-version: ${{ matrix.node-version }}
    # install dependencies
    - run: npm ci
    # build the project if necessary
    - run: npm run build --if-present
    - run: npm test

Believe it or not, but that's it!

Now when you push this, you should see a pipeline built under "Actions" as well as the status of the last build on the repository:

Notice the checkmark next to the commit hash. Clicking on it will also lead you to the build.

If any of your tests fail, the job will fail and alert you per email (You can configure this in your GitHub settings).

Furthermore, when a PR is created the build will also be triggered and you will see the results directly in the PR.

Take a look at the script I use for flooent: https://github.com/MZanggl/flooent/blob/latest/.github/workflows/ci.yml

And that's about it. I was pleasantly surprised by how easy it was to set it up. Next time let's check out how to add test coverage!

Aaand that's all there is to it. Now all that's left is to set up the CD workflow. Until then ;)

TypeScript to the rescue

With TypeScript all you need is one file tsconfig.json to handle all of the JS ecosystem madness, well most of it at least.

Sure, TypeScript is also something that you have to learn, and it doesn't come without its very own set of challenges, but let me guide you through it and I'm sure you will love it! It has so much more to offer than just transpiling your code...

So let's go ahead and create a little library.

I am not here to bash babel or anything, I know them providing all these different plugins sure is useful for many projects. But then there are so many other projects where you don't really need this flexibility. As always, judge for yourself which is the way to go in your particular use case.

Preparations

First let's create a new project, initialize the package, install typescript and create an empty config file.

mkdir my-lib
cd my-lib
npm init --yes
npm install typescript --save-dev
touch tsconfig.json

Alright, next let's create a typescript file so we can test the output.

mkdir src
cd src
touch index.ts

Go ahead and open the project in your favorite code editor (I recommend vs code since it already comes with full TS support).

// src/index.ts

export function scream(text) {
  const transformedText = text.toUpperCase()
  return `${transformedText}!!!!`
}

Relatively straight forward, take the input and scream it back out again.

Let's add a script to compile the code in package.json under scripts

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "compile": "tsc"
},

tsc stands for typescript compiler and is available since we installed the typscript dependency.

Finally, let's create the configurations inside tsconfig.json

{
  "compilerOptions": {
      "outDir": "./dist"
  },
  "include": [
      "src/**/*"
  ]
}

This simply tells TS to compile everything in the "src" folder and output the compiled files in a "dist" folder.

We can now run npm run compile to compile this code and we get the following output in dist/index.js:

"use strict";
exports.__esModule = true;
function scream(text) {
    var transformedText = text.toUpperCase();
    return transformedText + "!!!!";
}
exports.scream = scream;

Typescript transpiles it down all the way to ES3 and uses commonJS as the module resolution.

Note that you can use "outFile" instead of "outDir" to compile everything down to a single file.

There are a lot of tweaks that we can do here so let's explore some common compiler options.

target & module compiler options

{
  "compilerOptions": {
      "outDir": "./dist",
      "target": "ES5",
      "module": "CommonJS",
  },
  "include": [
      "src/**/*"
  ]
}

First I don't really want to go all the way down to ES3, ES5 is already enough. We can define this using the "target" option. Next, I want to be explicit about the module resolution so it's easy to see that we indeed use CommonJS.

If you are not familiar with the module resolution, try setting it to "ES2015". This would now compile the code to ES5, however use ES modules to import/export files

export function scream(text) {
    var transformedText = text.toUpperCase();
    return transformedText + "!!!!";
}

But let's revert that again, so people can use it in Node.

Enabling strict mode

I really recommend you to get your hands dirty with TypeScript and not only use it for transpiling, but especially as a compiler. A good way of doing this is enforcing types by enabling "strict" mode.

{
  "compilerOptions": {
      "outDir": "./dist",
      "target": "ES5",
      "module": "CommonJS",
      "strict": true
  },
  "include": [
      "src/**/*"
  ]
}

If you are using VSCode you should already see some red wiggly lines in index.ts, but go ahead and try compiling your code again using npm run compile.

You should get an error saying: "src/index.ts:1:24 - error TS7006: Parameter 'text' implicitly has an 'any' type."

To fix it, let's head over to index.ts and properly type it

export function scream(text: string) {
  const transformedText = text.toUpperCase()
  return `${transformedText}!!!!`
}

This leads to fantastic developer experience because of the powerful intellisense and early error & bug catching.

Declaration files

Since we transpile the code to JavaScript, we unfortunately lose all of the type information (for intellisense) again once we import the library somewhere else. To migitate that, Typescript allows us to emit so called declaration files. We simply have to instruct TS to do so

{
  "compilerOptions": {
      "outDir": "./dist",
      "target": "ES5",
      "module": "CommonJS",
      "strict": true,
      "declaration": true
  },
  "include": [
      "src/**/*"
  ]
}

This will now output ".d.ts" files in the dist folder during compilation.

Absolute imports

This one is probably not needed for a simple library but it's good to know. You can set the "src" folder to be the base url so you don't have to write things like import something from '../../../something.

{
  "compilerOptions": {
      "outDir": "./dist",
      "target": "ES5",
      "module": "CommonJS",
      "strict": true,
      "declaration": true,
      "baseUrl": "./src"
  },
  "include": [
      "src/**/*"
  ]
}

Say you have the file src/services/something, you can now simply do import something from 'services/something'.

lib

Remember when I was mentioning this in the beginning "Finally, you think you are all set and use [1, 2].includes(1) only to hear complaints from some users that the site is crashing". So how does TypeScript save us from this?

Well, just try adding that code into the "scream" method:

export function scream(text: string) {
  [1, 2].includes(1)
  const transformedText = text.toUpperCase()
  return `${transformedText}!!!!`
}

This now gets us the error Property 'includes' does not exist on type 'number[]'.ts(2339) and that is so so great.

Think about it!

We are targetting ES5 in the tsconfig.json, but "Array.prototype.includes" is an ES2016 (ES7) feature! TypeScript, by default, let's you know there is something missing in your setup. If you go ahead and change the target to "ES2016", your code can compile just fine again. But that's not what we want...

By default Typescript doesn't include these so called polyfills, just like babel. There are just too many ways one can implement them.

A simple way to emulate a ES2015/ES6 environment is to use babel-polyfill. (But be aware of what babel-polyfill does NOT include).

So with the polyfills in place, we can now use the "lib" option to tell TypeScript that we've taken care of this dilemma and to trust us on this.

{
  "compilerOptions": {
      "outDir": "./dist",
      "lib": ["ES2018"],
      "target": "ES5",
      "module": "CommonJS",
      "strict": true,
      "declaration": true,
      "baseUrl": "./src"
  },
  "include": [
      "src/**/*"
  ]
}

So we still target ES5, but are now also allowed to write ES2018 code.

So much more

There are some more options you can explore to customize and improve your TS experience: https://www.typescriptlang.org/docs/handbook/compiler-options.html, but the current options should be enough for many projects already.

Here is a gist you can save for future references.

The blade view

The documentation is a little incomplete in the repository. I was confused with app.$mount('#app') since in the blade files of the readme, there was no element matching the selector #app.

Actually, the complete blade view according to the examples would look like this

step 1. blade

<html>
    <head>
        <script defer src="{{ mix('app-client.js') }}">
    </head>
    <body>
        {!! ssr('js/app-server.js')->fallback('<div id="app"></div>')->render() !!}
        <script defer src="{{ mix('app-client.js') }}">
    </body>
</html>

step 2. Vue

The root component also gets the id app assigned.

<template
  <div id="app">
    <!-- ... --!>
  </div>
</template>

So when SSR fails for some reason it would fall back to <div id="app"></div> and the client-side render would take care of everything.

Otherwise, after the app has been rendered on the server, the client side mount app.$mount('#app') would still work properly because of step 2.

So this works, but having the same ID in multiple places is a little confusing. An easier solution would be to put #app in a wrapper class only in the blade view.

<html>
    <head>
        <script defer src="{{ mix('app-client.js') }}">
    </head>
    <body>
        <div id="app">
            {!! ssr('js/app-server.js')->render() !!}
        </div>
    </body>
</html>

Yes, even with SSR in place, we still need a client-side mount to let Vue add event listeners, deal with all the reactivity and lifecycle hooks. One example would be the mounted method which will only be executed on the client. SSR will only execute what is needed for the initial render.

What's my Node path in .env

In many cases, this might simply be

NODE_PATH=node

You know, the same way you can globally access Node for things like node some-file.js or node -v.

It doesn't perform SSR at all

By default, it is only activated for production. You can change this by first publishing the config file

php artisan vendor:publish --provider="Spatie\Ssr\SsrServiceProvider" --tag="config"

and then changing 'enabled' => env('APP_ENV') === 'production' to 'enabled' => true.

By now it should at least try to perform SSR. That means you are one step closer to finishing it. But now you might encounter problems like the following when Node tries to render the Vue app.

async await is crashing

We are talking about integrating this into an existing application. So be sure to check whether your version of Laravel-mix is not too outdated. In my case, it was not even on 2.0. An update to laravel-mix@2.1.14 was enough to fix these issues. You might want to consider updating even higher, but then be sure to check the release notes regarding the breaking changes.

All props are undefined in child component

Another error that turned out to be a version error. An update from 2.5 to the latest vue@2.6.10 fixed the error. In hindsight, the problem might have also occurred due to having different versions for Vue and vue-server-renderer.

Window is not defined in return window && document && document.all && !window.atob

Now it becomes a little more interesting. You will encounter this error as soon as you have styles in a Vue component. The reason for this is because vue-loder uses style-loader under the hood, which is responsible for dynamically adding the styles to the head during runtime. But there is one problem, it only works in the browser. Since SSR is rendered in Node, there is neither window nor document available. So this got me thinking, how is Nuxt.js doing it? They are also using vue-loader after all. The solution is quite easy: Extract the styles before they are rendered by Node. This is actually a good practice to do so, so let's set it up in laravel-mix.

The only thing we have to do is add the following to the options in webpack-mix.js.

mix.options({
    extractVueStyles: 'public/css/app.css',
})

All styles are being extracted into a single file app.css. If you have individual pages that use Vue and you would like to have a separate CSS file for each page, go with the following:

mix.options({
    extractVueStyles: 'public/css/[name].css',
})

This would create the following files for example

> /public/css/js/login.css
> /public/css/js/registration.css
> /public/css/js/search.css

Apart from extracting Vue styles you also have to remove importing CSS files in JavaScript.

import "some-library/some-style.css"

Instead, move these to some global style sheet. You might already have some merging technique in place for that. Again, it's a good practice to do so anyway ;)

webpackJsonp is not defined

If this happens, you are likely extracting Node modules out into a vendor file. This has various performance benefits.

mix.extract(['vue']);

Why is it crashing? If you look at the output of manifest.js it creates a global variable webpackJsonp and every JavaScript file will access this global variable to resolve the dependencies. Node.js, however, would not get manifest.js as well as vendor.js and therefore would be missing global variables and crash when trying to render your app.

One way to still make use of this feature is to have one webpack.mix.js file for only the server side scripts and another one for the client side scripts. This comment shows how to do exactly that. Unfortunately, that is the only way I know of now how to keep extracting your dependencies.

window / document / $ / localStorage / etc. is not defined

By now, your page might already render correctly, but there are a couple more traps to run into.

Imagine the following

data() {
    name: localStorage.getItem('name')
}

and... crash!

This has nothing to do with the plugin or Laravel at this point, but simply something you have to be aware of when using SSR. window/document/localStorage and much more only exist on the client, not within Node.

There are two workarounds to fix the crash.

1. check the existence of variables before accessing these kinds of objects

data() {
    name: typeof localStorage !== 'undefined' ? localStorage.getItem('name') : null
}

2. Move the logic to the mounted method.

data() {
    name: null
},
mounted() {
    // client only
    this.name = localStorage.getItem('name')
}

In Nuxt.js you could also make use of the global process.client boolean to check whether the code is being executed on the server or on the client.

Conclusion

Having to more or less manually set up SSR really makes one appreciate frameworks like Nuxt.js. But the good news is that SSR in Laravel is definitely possible.

If there is any other problem, think: How is Nuxt.js doing it? Because there is certainly a way to do it.

It works by first defining your promise like this:

import promistate from 'promistate'

const userPromise = promistate(async function callback(id) {
    return fetch(`/api/users/${id}`).then(res => res.json())
})

This won't execute the callback right away but userPromise already holds a lot of useful properties for us. For example, we can say userPromise.value to get the resolved value (currently null), userPromise.isPending to know if the promise is pending, and userPromise.error to see if there was an error fetching the resource. There are a couple of more useful properties...

Now how do we actually fetch? We simply do userPromise.load(1). This will now set isPending to true, and after the promise settled, it will mutate userPromise.value if successful, or userPromise.error if an error was thrown.

Now let's see it in action in a Vue component.

<template>
  <div>
    <button @click="todosPromise.load()">load</button>
    <button @click="todosPromise.reset()">reset</button>

    <div v-if="todosPromise.error">Whoops!</div>
    <div v-else-if="todosPromise.isPending">Pending...</div>
    <div v-else-if="todosPromise.isEmpty">empty...</div>
    <div v-else>
      <div v-for="todo in todosPromise.value" :key="todo.title">{{ todo.title }}</div>
    </div>
  </div>
</template>

<script>
import promistate from "promistate";

export default {
  data() {
    const todosPromise = promistate(() =>
      fetch("https://jsonplaceholder.typicode.com/todos").then(res =>
        res.json()
      )
    );

    return { todosPromise };
  }
};
</script>

Alright, what about react? This requires the use of the usePromistate hook.

import React from "react";
import { usePromistate } from "promistate/lib/react";

const api = "https://jsonplaceholder.typicode.com/todos";

export default function App() {
  const [todosPromise, actions] = usePromistate(
    () => fetch(api).then(res => res.json()),
    { defaultValue: [] }
  );

  return (
    <div className="App">
      <button onClick={actions.load}>load</button>
      <button onClick={actions.reset}>reset</button>

      {todosPromise.isPending && <div>pending...</div>}
      {todosPromise.isEmpty && <div>no results...</div>}
      {todosPromise.value.map(todo => (
        <div key={todo.id}>{todo.title}</div>
      ))}
    </div>
  );
}

In the docs, I have an entire list of examples in different libraries including React.js, Vue.js, Angular, Svelte, Alpine.js, and Vanilla JS.

Common workarounds

There are common workarounds for this, which are all about telling JavaScript that the IIFE is indeed a new statement, most notably

const http = require('http')

void (async () => { // < note the void at the beginning

})()

or

const http = require('http'); // < note the semicolon

(async () => {

})()

or even

const http = require('http')

!(async () => { // < note the exclamation mark

})()

Labels

The above workarounds are nothing new, but here is something you might have not seen yet.

const http = require('http')

IIFE: (async () => {

})()

Yup, labels work as well. You can put labels before any statement. We can replace IIFE with anything we want at this point as long as it follows the syntax. If it works as a variable name, it works as a label identifier.

一か八か: 1 + 1

Labels are actually quite interesting. Look at the following code snippet taken from MDN.

foo: {
  console.log('this will be executed');
  break foo;
  console.log('this will not be executed');
}
console.log('this will be executed as well');

Conclusion

Since labels are not so well known, it is probably better to stick with semicolons or void, but it is nonetheless interesting. I like how they add some documentation to IIFEs. Well, let's just wait a little more for top level await.

Say, you now have another function that depends on isAM:

function isDeliverable(item) {
  if (isAM()) {
    return false
  }

  // ...

  return true
}

For whatever reason, items are not deliverable before 12 pm.

Now how do we test this method? Passing a date to isDeliveryable certainly does not make much sense.

This is where we can make use of a handy npm library called timekeeper.

npm i timekeeper --save-dev

timekeeper allows us to travel to a different time by mocking the native Date object.

Here's how we can test will look like:

const timekeeper = require('timekeeper')
const { isDeliverable } = require('./delivery')

it('is not deliverable before 12 noon', () => {
  timekeeper.travel(new Date(2020, 1, 1, 7))

  expect(isDeliverable({ ... })).toBeFalsy()

  timekeeper.reset()
})

Awesome!! It's like Rails.

As this mutates the native Date object, it's best to not run tests in parallel!

Microservices (video)

Or how they can go wrong...

LCH colors in CSS

Did you know that browsers can not display all available colors? It's missing like 50%?

toJSON

Did you know?

If an object has a toJSON method and you call JSON.stringify (like when returning a response from a server), the result of toJSON will be stringified instead of the object. For a use case in the wild, check out the docs for adonis.js.

git stash-unstaged

Ever wanted to stash your code, but keep everything you staged (with git add .)

git config --global alias.stash-unstaged "stash save --keep-index -u"

git undo-commit

This will allow you to remove the latest commit and move all the changes back into your working directory. With this, I often prefer committing instead of stashing code that I need for later, because it makes it so much simpler than searching through a list of stashes.

git config --global alias.undo-commit "reset HEAD~ --soft"

Let's see what's in stock for next year ✌️

I'm excited about the possibilities this opens up. Here are some use cases I can think of:

• Getting and setting cookies
• Logging information about the current request
• session flashing
• Wrapping database calls in a transaction without passing the transaction object to each query (sometimes in separate function/class).

This was just meant as a short introduction to this new feature. Obviously, this also opens up room for complexity and dirty code. For example, it lets you access the request payload from anywhere in your application. Something you probably don't want to make use of in too many places as it couples the request with your entire code base. Well, let's see where this takes us!

The funny thing about this solution is that this non-reactive approach is the default behaviour with Vanilla Js. The app was overreacting.

Working with state

Vue

// Counter.vue

<template>
    <button @click="increment">{{ count }}</button>
</template>
<script>
    export default {
        data() {
            return {
                count: 1
            }
        },
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

and react

import { useState } from 'react'

function Counter() {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    return <button onClick={increment}>{ count }</button>
}

As you can see, react's useState returns a tuple with a set function as the second argument. In vue, you can directly set the value to update the state.

With hooks, Whenever our state/props get updated, the Counter method is executed again. Only the first time though it initiates the count variable with 1. That's basically the whole deal about hooks. This concept is one of the few that you have to understand with hooks.

vue pros/cons

(+) predefined structure

(-) you can not just import something and use it in the template. It has to be laid out in one of the various concepts of vue data, methods, computed, $store etc. This also makes some values needlessly reactive and might cause confusion (why is this reactive? Does it change? Where?)

react pros/cons

(+) It's just a function

(-) Actually it's a function that gets executed every time state or props change. That way of thinking is likely no problem for those used to the old stateless functional components of react, but for people who exclusively used vue, a new way of thinking is required. It just doesn't come off natural at first.

(-) Hooks have various rules on where and how you have to use them.

Passing props

// Counter.vue

<template>
    <div>
        <h1>{{ title }}</h1>
        <button @click="increment">{{ count }}</button>
    </div>
</template>
<script>
    export default {
        data() {
            return {
                count: 1
            }
        },
        props: {
            title: String
        },
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

and react

import { useState } from 'react'

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    return (
        <>
            <h2>{title}</h2>
            <button onClick={increment}>{count}</button>
        </>
    )
}

vue pros/cons

(+) You can be specific about the types of your props (without TS)

(-) access the same way as state (this.xxx), but actually behaves differently (e.g. assigning a new value throws a warning). This makes beginners think they can just go ahead and update props.

react pros/cons

(+) easy to understand -> props are just function arguments

Child components

Let's extract the button into a child component.

vue

// Button.vue

<template>
    <button @click="$emit('handle-click')">
        {{ value }}
    </button>
</template>
<script>
    export default {
        props: ['value']
    }
</script>

// Counter.vue

<template>
    <div>
        <h1>{{ title }}</h1>
        <Button @handle-click="increment" :value="count" />
    </div>
</template>
<script>
    import Button from './Button'

    export default {
        components: {
            Button,
        },
        data() {
            return {
                count: 1
            }
        },
        props: ['title'],
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

vue introduces a "new" concept events at this point.

The react counterpart

import { useState } from 'react'

function Button({value, handleClick}) {
    return <button onClick={handleClick}>{value}</button>
}

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    return (
        <>
            <h2>{title}</h2>
            <Button value={count} handleClick={increment}/>
        </>
    )
}

vue pros/cons

(+) clear separation of concerns

(+) events play very nice with vue devtools

(+) Events come with modifiers that make the code super clean. E.g. @submit.prevent="submit" < applies event.preventDefault()

(-) weird casing rules

(-) sort of an additional concept to learn (events). Actually events are similar to native events in the browser. One of the few differences would be that they don't bubble up.

react pros/cons

(+) we are not forced to create separate files

(+) no concepts of events -> just pass the function in as a prop. To update props, you can also just pass in a function as a prop

(+) overall shorter (at least in this derived example)

Some of the pros/cons are contradicting, this is because in the end it all comes down to personal preference. One might like the freedom of react, while others prefer the clear structure of vue.

Slots

Vue introduces yet another concept when you want to pass template to a child component. Let's make it possible to pass more than a string to the button.

// Button.vue

<template>
    <div>
        <button @click="$emit('handle-click')">
            <slot>Default</slot>
        </button>
        <slot name="afterButton"/>
    </div>
</template>
<script>
    export default {}
</script>

// Counter.vue

<template>
    <div>
        <h1>{{ title }}</h1>
        <Button @handle-click="increment">
            <strong>{{ count }}</strong>
            <template v-slot:afterButton>
                Some content after the button...
            </template>
        </Button>
    </div>
</template>
<script>
    import Button from './Button'

    export default {
        components: {
            Button,
        },
        data() {
            return {
                count: 1
            }
        },
        props: ['title'],
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

<strong>{{ count }}</strong> will go inside <slot></slot> since it is the default/unnamed slot. Some content after the button... will be placed inside <slot name="afterButton"/>.

And in react

import { useState } from 'react'

function Button({AfterButton, handleClick, children}) {
    return (
        <>
            <button onClick={handleClick}>
                {children}
            </button>
            <AfterButton />
        </>
    )
}

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    return (
        <>
            <h2>{title}</h2>
            <Button value={count} handleClick={increment} AfterButton={() => 'some content...'}>
                <strong>{ count }</strong>
            </Button>
        </>
    )
}

vue pros/cons

(-) slots can be confusing. Especially when you send data from the child component to the slot.

(-) Passing slots down multiple components is even more confusing

(-) another concept to learn

These are consequences of vue using a custom templating language. It mostly works, but with slots it can become complicated.

Slots will get simplified in vue 3

react pros/cons

(+) no new concept - Since components are just functions, just create such a function and pass it in as a prop

(+) Doesn't even have to be a function. You can save template(jsx) in a variable and pass it around. This is exactly what happens with the special children prop.

Computed fields

Let's simplify the examples again

// Counter.vue

<template>
    <div>
        <h1>{{ capitalizedTitle }}</h1>
        <button @click="increment">{{ count }}</button>
    </div>
</template>
<script>
    export default {
        data() {
            return {
                count: 1
            }
        },
        props: ['title'],
        computed: {
            capitalizedTitle() {
                return title.toUpperCase()
            }
        },
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

react

import { useState, useMemo } from 'react'

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)
    const capitalizedTitle = title.toUpperCase()

    return (
        <>
            <h2>{capitalizedTitle}</h2>
            <button onClick={increment}>{count}</button>
        </>
    )
}

In vue, computed fields serve not one, but two purposes. They keep the template clean and at the same time provide caching.

In react, we can simply declare a variable that holds the desired value to solve the problem of keeping the template clean. (const capitalizedTitle = title.toUpperCase())

In order to cache it as well, we can make use of react's useMemo hook.

const capitalizedTitle = useMemo(() => title.toUpperCase(), [title])

In the second argument we have to specify the fields required to invalidate the cache if any of the fields' value changes.

useMemo works like this:

title changes outside of component -> Counter function runs since prop got updated -> useMemo realizes that the title changed, runs the function passed in as the first argument, caches the result of it and returns it.

vue pros/cons

(+) nice and clear separation of concerns

(-) you define computed fields in functions, but access them like state/props. This makes perfect sense if you think about it, but I have received questions about this repeatedly by peers.

(-) There is some magic going on here. How does vue know when to invalidate the cache?

(-) Computed fields serve two purposes

react pros/cons

(+) To keep the template clean, there is no new concept to learn, just save it in a variable, and use that variable in the template

(+) You have control over what gets cached and how

Watch

// Counter.vue

<template>
    <button @click="increment">{{ capitalizedTitle }}</button>
</template>
<script>
    export default {
        data() {
            return {
                count: 1
            }
        },
        watch: {
            count() {
                console.log(this.count)
            }
        },
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

react

import { useState, useEffect } from 'react'

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    useEffect(() => {
        console.log(count)
    }, [count])

    return (
        <button onClick={increment}>{count}</button>
    )
}

useEffect works pretty much the same way as useMemo, just without the caching part.

setCount -> Counter function runs -> useEffect realizes that the count changed and will run the effect.

vue pros/cons

(+) clean, easily understandable, nailed it!

react pros/cons

(+) You can specify multiple fields instead of just one field

(-) The purpose of useEffect is not as clear as vue's watch. This is also because useEffect is used for more than one thing. It deals with any kind of side effects.

mounted

Doing something when a component has mounted is a good place for ajax requests.

vue

// Counter.vue

<template>
    <button @click="increment">{{ capitalizedTitle }}</button>
</template>
<script>
    export default {
        data() {
            return {
                count: 1
            }
        },
        mounted() {
            // this.$http.get...
        },
        methods: {
            increment() {
                this.count++
            }
        }
    }
</script>

and react

import { useState, useEffect } from 'react'

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    useEffect(() => {
        // ajax request...
    }, [])

    return (
        <button onClick={increment}>{count}</button>
    )
}

You can use the same useEffect as before, but this time specify an empty array as the second argument. It will execute once, and since there is no state specified like before ([count]), it will never evaluate a second time.

vue pros/cons

(+) clean and easy.

(-) Initiating something and cleaning up after it has to be in two different methods, which makes you jump unnecessarily and forces you to save variables somewhere else entirely (more on that in a moment)

react pros/cons

(-) Very abstract. I would have preferred a dedicated method for it instead. Cool thing is, I have the freedom to just make it.

(-) useEffect callback is not allowed to return promises (causes race conditions)

(+) clean up in very same function:

Turns out useEffect comes with one rather interesting and neat feature. If you return a function within useEffect, it is used when the component gets unmounted/destroyed. This sounds confusing at first, but saves you some temporary variables.

Look at this

import { useState, useEffect } from 'react'

function App() {
    const [showsCount, setShowsCount] = useState(true);

    return (
    <div className="App">
        <button onClick={() => setShowsCount(!showsCount)}>toggle</button>
        {showsCount && <Counter />}
    </div>
    );
}

function Counter({ title }) {
    const [count, setCount] = useState(1)
    const increment = () => setCount(count+1)

    useEffect(() => {
        const interval = setInterval(() => {
            increment()
            console.log("interval")
        }, 1000)

        return function cleanup() {
            clearInterval(interval)
        }
    }, [])

    return (
        <button>{count}</button>
    )
}

The interesting part is inside useEffect. In the same scope we are able to create and clear an interval. With vue, we would have to initiate the variable first somewhere else, so that we can fill it in mounted and cleanup inside destroy.

Others

vue

(+) v-model directive

(+) first party tools like SSR, VueX and vue-router that play very nice with devtools

(+) Scoped CSS out of the box. Super easy to use SCSS

(+) Feels more like traditional web development and makes onboarding easier

react

(+) More and more things become first party and part of the react core library (hooks, code splitting, etc.)

(+) many libraries to choose from

Conclusion

vue limits you in certain ways, but by that, it also structures your code in a clean and consistent way.

React doesn't limit you much, but in return, you have a lot more responsibility to maintain clean code. This I think became much easier with the introduction of hooks.

But then of course, with all the competition going on, vue is not going to ignore the benefits of react hooks and has already released an rfc for function-based components. It looks promising and I am excited where it will lead to!

Let's talk about these conditionals...

I actually created two traits to overcome all these conditionals. If you are new to traits please check out in the repositories on how to set them up.

Optional

Repository: https://github.com/MZanggl/adonis-lucid-optional-queries

With Optional we will be able to turn the index method into

async index({ response, request }) {    
    const posts = await Post.query()
        .optional(query => query
            .where('category_id', request.input('category_id'))
            .byEncodedKeyword(request.input('keyword'))
            .whereIn('tags', request.input('tags'))
        )
        .where('active', true)
        .fetch()

    return response.json({ posts: posts.toJSON() })
}

We were able to get rid of all the conditionals throughout the controller by wrapping optional queries in the higher order function optional. The higher order function traps the query object in an ES6 proxy that checks if the passed arguments are truthy. Only then will it add the constraint to the query.

When

Repository: https://github.com/MZanggl/adonis-lucid-when

The second trait I wrote implements Laravel's when method as a trait. Optional has the drawback that you can only check for truthy values, sometimes you might also want to check if an input is a certain value before you apply the constraint. With when we can turn the search method into

async index({ response, request }) {    
    const posts = await Post.query()
        .when(request.input('category_id'), (q, value) => q.where('category_id', value))
        .when(request.input('keyword'), (q, value) => q.byEncodedKeyword(value))
        .when(request.input('sort') === 1, q => q.orderBy('id', 'DESC'))
        .where('active', true)
        .fetch()

        return response.json({ posts: posts.toJSON() })
    }

When works similar to Optional in that it only applies the callback when the first argument is truthy. You can even add a third parameter to apply a default value in case the first argument is not truthy.

Of course we can also combine these two traits

async index({ response, request }) {    
    const posts = await Post.query()
        .optional(query => query
            .where('category_id', request.input('category_id'))
            .byEncodedKeyword(request.input('keyword'))
            .whereIn('tags', request.input('tags'))
        )
        .when(request.input('sort') === 1, q => q.orderBy('id', 'DESC'))
        .where('active', true)
        .fetch()

    return response.json({ posts: posts.toJSON() })
}

An even more elegant way would be to use filters. Check out this module.

We could turn our controller into

const Post = use('App/Models/Post')

class PostsController {
    async index({ response, request }) {
        const posts = await Post.query()
            .filter(request.all())
            .fetch()

        return response.json({ posts: posts.toJSON() })
    }
}

This has the benefit that it removes all constraints from the controller, but also the drawback that it is not 100% clear what is happening without a close look to all the filters you created.

Conclusion

There's always more than one way to skin a cat, we could have also extracted the queries and conditions into a separate class specifically for searching this table (kind of like a repository pattern but for searching).

I hope this post gave you some ideas on how to clean up your search queries.

So let's step away from these rather unfortunately named acronyms and into the code.

const ajax = {
  a: 'Asynchronous',
  j: {
    j: 'Java',
    s: 'Script',
    o: 'Object',
    n: 'Notation'
  },
  a2: 'and',
  x: {
    x: 'Extensible',
    m: 'Markup',
    l: 'Language'
  }
}

Here we have ajax layed out in a two dimensional object.

What happens if we copy this object into another object

const obj = ajax
obj.x = null

obj.x //? null
ajax.x //? null

This won't work. obj will be merely a reference to ajax. Changing one will change the other respectively. That's the way objects work in JavaScript.

How about this?

const obj = Object.assign({}, ajax) 
// or: const obj = {...ajax}

obj.x = null

obj.x //? null
ajax.x //? { x: 'Extensible', m: 'Markup', l: 'Language' }

Nice, we created an actual copy! Or did we...?

const obj = Object.assign({}, ajax)

obj.x.l = 'lang'

obj.x.l //? lang
ajax.x.l //? lang

Turns out Object.assign as well as ES6 spread syntax are merely doing a shallow-copy!

So how can we possibly copy the entire object, i.e. deep-copy?

A rather hackish solution you often see is the following

const obj = JSON.parse(JSON.stringify(ajax))

While this would work in our example, it would simply remove any methods on the object. It will also not work on maps and sets.

The sad truth is, JavaScript does not provide such functionality out of the box. You can either create your very own deep copy method or make use of existing solutions.

PS. In JavaScript arrays are objects, so everything we talked about also applies to arrays.

I am going to list down some high level alternatives here: (if you know more, let me know)

• https://adonisjs.com/ (inspired by Laravel ❤️)
• https://nestjs.com/
• https://sailsjs.com/

While the inital learning curve is definitely higher, you will benefit from it in the long run. These frameworks can teach you a lot about clean architecture and code, commonly applied concepts, keeping your application secure and how to focus only on the application you set out to build.

Don't get me wrong, I can certainly see how building everything from scratch is a good learning experience, it was for me! But after I have done it one time and wanted to start another application, I didn't really feel like doing it all over again. You should also be very careful with using your custom built authentication system on production.

Another thing would be onboarding, people familiar with the high level framework can immediately jump into coding, rather than spending a day trying to understand the architecture of the project only to fix a small bug. In case they don't know the framework yet, there is at least documentation and blog posts to read about it.

At the end of the day, we want to build applications and be confident about the code we have written.

Btw. I am not promoting some revolutionary new library here. We are simply exploring ideas. I still created a GitHub repo for this so you can check out the whole code if you want.

But first, how do we create arrays in JavaScript?

The classic

const numbers = [1, 2, 3]

and the maybe not so well known

const numbers = new Array(1, 2, 3)

But the above doesn't do what you would expect when you only pass one argument. new Array(3) would create an array with three empty values instead of an array with just one value being 3.

ES6 introduces a static method that fixes that behaviour.

const numbers = Array.of(1, 2, 3)

Then there is also this

const array = Array.from({ length: 3 })
//? (3) [undefined, undefined, undefined]

The above works because Array.from expects an array-like object. An object with a length property is all we need to create such an object.

It can also have a second parameter to map over the array.

const array = Array.from({ length: 3 }, (val, i) => i)
//? (3) [0, 1, 2]

With that in mind, let's create Steray, Array on Steroids.

With ES6 and the introduction of classes it is possible to easily extend arrays

class Steray extends Array {
    log() {
        console.log(this)
    }
}

const numbers = new Steray(1, 2, 3)
numbers.log() // logs [1, 2, 3]

So far so good, but what if we have an existing array and want to turn it into a Steray?

Remember that with Array.from we can create a new array by passing an array-like object, and aren't arrays kind of included in that definition?

Which ultimately means we can do this

const normalArray = [1, 2, 3]
const steray = Steray.from(normalArray)

or alternatively

const normalArray = [1, 2, 3]
const steray = Steray.of(...normalArray)

Let's start adding some methods to Steray. Inside steray.js we can just add the long awaited pluck method to the class

pluck(key) {
    return this.map(item => item[key])
}

and that's it. Elegant and powerful.

Setting up tests

But how do we know this works? We don't know want to go into the browser every time and test our class in the console. So let's quickly set up unit testing, so we can be confident that what we are doing is correct.

Create the following directory structure

steray
    src
        steray.js
    test
        sterayTest.js

With node and npm installed, install the unit testing framework mocha globally.

npm install mocha -g

Next let's initialize package.json by running npm init in the root of the directory. Follow the instructions until it creates a package.json file. When it asks you for the test script enter mocha. Alternatively you can also change this later inside package.json.

"scripts": {
    "test": "mocha"
},

Next, install the assertion library chai locally

npm install chai --save-dev

And that's all we had to setup. Let's open up sterayTest.js and write our first test

const expect = require('chai').expect
const Steray = require('../src/steray')

describe('pluck', function() {
    it('should pluck values using the "name" prop', function() {
        const users = new Steray( 
            { name: 'Michael' },
            { name: 'Lukas' },
        )

        const names = users.pluck('name')
        expect(names).to.deep.equal([ 'Michael', 'Lukas' ])
    })
})

Run the tests using npm run test in the root of the directory and it should output that one test is passing. With that out of the way we can now safely continue writing new methods, or change the implementation of pluck without having to worry about our code breaking.

Let's add some more methods, but this time in the spirit of test driven development!

You know what I really don't like? These pesky for loops.

for (let i; i < 10; i++)

Is it let i or const i, is it < or <=? Wouldn't it be nice if there was an easier way to achieve this. While you can use the syntax we learned earlier Array.from({ length: 10 }, (value, index) => index) it is unnecessarily verbose. Inspired by lodash and Laravel collections, let's create a static times method.

In order for you to see the method in action, let's first create the unit test.

describe('times', function() {
    it('should return an array containing the indices 0 and 1', function() {
        const numbers = Steray.times(2, i => i)
        expect(numbers).to.deep.equal([ 0, 1 ])
    })
})

Try running npm run test and it should return errors because times doesn't exist yet.

I will always show the test first, so you can try implementing the method yourself before looking at my implementation. Found a better solution? Send in a PR!

So, here is my implementation of times in steray.js

static times(length, fn) {
    return this.from({ length }, (value, i) => fn(i))
}

Sometimes you might get confused if there is a long chain and you want to tap into the process to see what is going on. So let's build that functionality.

An example use case would be

[1, 2, 3, 4, 5]
    .filter(i => i < 4)
    .map(i => i * 10)
    .tap(console.log)
    .find(i => i === 20)

tap executes the function but then just returns the very same array again unmodified. tap does not return what the callback returns. For such a functionality, let's create another method pipe.

Here are the tests

describe('tapping and piping', function() {
    it('should execute callback one time', function() {
        let i = 0
        new Steray(1, 2, 3).tap(array => i = i + 1)

        expect(i).to.equal(1)
    })

    it('should return original array when tapping', function() {
        const array = new Steray(1, 2, 3).tap(() => 10)
        expect(array).to.deep.equal([1, 2, 3])
    })

    it('should return result of pipe', function() {
        const piped = new Steray(1, 2, 3).pipe(array => array.length)
        expect(piped).to.equal(3)
    })
})

And here is the implementation

tap(fn) {
    fn(this)
    return this
}

pipe(fn) {
    return fn(this)
}

It's amazing how small yet powerful these methods are!

Remember how in the previous blog post we were turning the users array into a hashMap grouped by the group key.

Let's also create this functionality by implementing a new method groupBy! Here is the test

describe('groupBy', function() {
    it('should hashMap', function() {
        const users = new Steray( 
            { name: 'Michael', group: 1 },
            { name: 'Lukas', group: 1 },
            { name: 'Travis', group: 2 },
        )

        const userMap = users.groupBy('group')

        expect(userMap).to.deep.equal({
            '1': [
                { name: 'Michael', group: 1 },
                { name: 'Lukas', group: 1 },
            ],
            '2': [
                { name: 'Travis', group: 2 },
            ]
        })
    })
})

and here is the implementation

groupBy(groupByProp) {
    return this.reduce((result, item) => {
        const id = item[groupByProp]
        result[id] = result[id] || new []
        
        result[id].push(rest);

        return result;
    }, {})
}

While this works, we might run into problems at one point. I will add another unit test to illustrate what can go wrong.

it('should hashMap using Steray array', function() {
    const users = new Steray( 
        { name: 'Michael', group: 1 },
        { name: 'Lukas', group: 1 },
        { name: 'Travis', group: 2 },
    )

    const userMap = users.groupBy('group')
    const groupOne = userMap['1']
    const isInstanceOfSteray = (groupOne instanceof Steray)
    expect(isInstanceOfSteray).to.be.true
})

What went wrong is result[id] = result[id] || [], specifically []. Since we create a normal array, all our newly implemented methods will not be available.

To fix this, let's use result[id] = result[id] || new Steray instead.

While the test will pass, the solution is also not 100% clean. What if we later wanted to move this function into its own file and import it here, wouldn't it create circular dependencies? Also it would be nice if it would be unaware of Steray.

A better solution in my opinion is the following

result[id] = result[id] || new this.constructor

this refers to the steray array and with this.constructor we get the class Steray dynamically.

There is a lot more we can add really

• deduplicating
• chunking
• padding
• prepending data to an array without transforming the original array (unlike unshift)

just to name a few.

You can find the Steray class including the unit tests and the above mentioned methods like chunk, pad, unique and prepend in the following GitHub repo.

An alternative to subclassing

Eventually our class may grow into a massive clutter of helper functions and you might run into certain limits.

A different approach would be to go completely functional with ramda. Ramda has the extra benefit that it also has methods for objects, strings, numbers, even functions.

An example of ramda would be

const R = require('ramda')

const users = [
    { name: 'Conan', location: { city: 'Tokyo' } },
    { name: 'Genta', location: { city: 'Tokyo' } },
    { name: 'Ayumi', location: { city: 'Kawasaki' } },
]

const getUniqueCitiesCapitalized = R.pipe(
    R.pluck('location'),
    R.pluck('city'),
    R.map(city => city.toUpperCase()),
    R.uniq()
)
const cities = getUniqueCitiesCapitalized(users)

expect(cities).to.deep.equal(['TOKYO', 'KAWASAKI'])

So how about we combine the two, a simple array subclass with the power of consuming ramda functions. I know I know, we are sort of abusing ramda at this point, but it's still interesting to check it out. We just need a new name..., our Array class is not really on steroids anymore, it's quite the opposite, so let' call it Yaseta, the Japanese expression when somebody lost weight.

Let's install ramda using npm install ramda --save-dev (we only need it for the tests) and create some tests, so we can see how we will use our new library.

// test/yasetaTest.js

const expect = require('chai').expect
const Yaseta = require('../src/yaseta')
const pluck = require('ramda/src/pluck')

describe('underscore methods', function() {
    it('returns result of callback', function() {
        const numbers = new Yaseta(1, 2)
        const size = numbers._(array => array.length)

        expect(size).to.equal(2)
    })

    it('returns result of assigned callback using higher order function', function() {
        const users = new Yaseta(
            { name: 'Conan' },
            { name: 'Genta' }
        )

        // this is how ramda works
        const customPluck = key => array => {
            return array.map(item => item[key])
        }

        const usernames = users._(customPluck('name'))

        expect(usernames).to.deep.equal(['Conan', 'Genta'])
    })

    it('can assign ramda methods', function() {
        const users = new Yaseta(
            { name: 'Conan' },
            { name: 'Genta' }
        )

        const usernames = users._(pluck('name'))

        expect(usernames).to.deep.equal(['Conan', 'Genta'])
    })
})