Vite.js is a build tool that can provide a similar feedback loop when doing web development, but this time the changes we make in our app are reflected instantly in our browser.

An instant connection with our creations is incredibly valuable—whether we are using one of the latest frontend frameworks, or just standard JS and CSS 😃

If you would like to play first and read later, jump to Getting Started.

Why is Vite.js so fast? ⚡️

During development, instead of bundling the entire application it leverages native ESM imports, which are supported by all modern browsers.

Browsers will request files imported in ESM scripts as needed, which can then be transformed and served on demand by the Vite.js web server. Any code that is not imported in the current page will not be processed nor served.

Because it doesn't need to bundle everything, the server starts really fast even on large applications, and changes are reflected instantly thanks to hot module replacement which will push updates to the browser using websockets.

As an optimization, Vite.js will pre-bundle large dependencies to reduce the amount of requests that the browser must make to the web server.

What about production?

To ensure optimal loading performance in production, Vite.js provides a build command to bundle our code, which provides many performance optimizations out of the box, with features such as asset-fingerprinting and tree-shaking.

As a result, Vite.js provides a great balance. Smooth and enjoyable experience during development. Best performance practices in production.

Covering the basics 📖

Vite.js enhances ESM imports to support various features that are typically seen in bundler-based setups, such as importing images or JSON files, or injecting styles.

import logoUrl from './logo.svg' // a URL to reference the icon

import packageInfo from './package.json' // a parsed JSON object

import { debounce } from 'lodash-es' // npm dependency

Configuration and Plugins 🛠

Configuration in Vite.js revolves around a vite.config.ts file, usually placed at the root of the project, with autocompletion support thanks to TypeScript.

Vite.js is designed for extensibility, and compatible with many rollup.js plugins. Because of the conventions in place, plugins are easy to install and easy to use.

The Plugin API is well documented, and enables the creation of new plugins.

import { defineConfig } from 'vite'
import EnvironmentPlugin from 'vite-plugin-environment'

export default defineConfig({
  plugins: [
    EnvironmentPlugin(['API_KEY', 'RACK_ENV']),
  ],
})

vite.config.ts

Styles 🎨

Importing CSS files will inject their content via a <style> tag with HMR support. Changes are reflected instantly in the browser without a full page reload, making it more enjoyable to iterate on a design.

import './styles.scss' // inject styles in the page
import classes from './theme.module.css' // CSS Modules

PostCSS is supported out of the box. If we prefer a CSS preprocessor like Sass all we need to do is add the relevant package and use the appropriate file extensions.

npm install -D sass

Now that we have a sense of the role of imports and plugins in Vite.js, let's take a look and see how we can leverage all this goodness in a Ruby web app.

By using Vite.js we can leverage tools in the Node.js ecosystem—such as Sass, PostCSS and Autoprefixer—without the need for Ruby integrations.

Using it in Ruby

Vite Ruby is a library that provides Vite.js integration for Ruby applications, with first-party support for frameworks such as Rails and Jekyll.

It uses conventions similar to those in webpacker to infer the entrypoints of our application, and provides tag helpers to render script and style tags that reference these entrypoints which will be processed by Vite.js.

The following sections use Rails, but aside from different tag helper names, the concepts are the same for other frameworks such as Hanami and Padrino.

See the installation guide for more information.

Getting started

To get started let's add Vite Ruby to our Gemfile and run bundle install.

gem 'vite_rails'

Once the gem is installed we can run bundle exec vite install to get a basic setup, including configuration files and installing npm packages.

The vite-plugin-ruby package will take care of detecting entrypoints in our app, and configure Vite.js based on the Ruby app structure.

import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'

export default defineConfig({
  plugins: [
    RubyPlugin(),
  ],
})

vite.config.ts

The install command will also add the following tag helpers to the app layout:

<html>
  <head>
    ...
    <%= vite_client_tag %>
    <%= vite_javascript_tag 'application' %>
  </head>

app/views/layouts/application.html.erb

vite_client_tag renders a script referencing the Vite.js client, which connects over websockets to the Vite.js development server to receive updates as we make changes to the imported files.

vite_javascript_tag renders a script referencing a file in the entrypoints directory, which is served by Vite.js during development. The sample file:

console.log('Vite ⚡️ Rails')

app/frontend/entrypoints/application.js

Playing with Vite.js

Now we can restart our Ruby web server to load Vite Ruby, start the Vite.js development server by running bin/vite dev, and visit any page.

If we inspect the browser console, we should see the following output:

[vite] connecting...
Vite ⚡️ Rails
[vite] connected.

Let's experiment with styles by creating a new stylesheet:

html, body {
  background-color: #CC0000;
}

app/frontend/styles/background.css

We can import it directly from our JS entrypoint to see a colored background:

import '~/styles/background.css'

console.log('Vite ⚡️ Rails')

app/frontend/entrypoints/application.js

Now, let's see how Vite.js performs updates by modifiying our styles and saving:

html, body {
  background-color: #FFE02E;
}

Damn, that's fast! ⚡️

If we check the console logs, we can see more output from the Vite.js client:

[vite] hot updated: /styles/background.css

The HMR mechanism is at the heart of the development experience in Vite.js ❤️

An example with Stimulus

To register all of our Stimulus controllers, we can leverage glob imports:

const controllers = import.meta.glob('./**/*_controller.js', { eager: true })

Vite.js will statically replace the glob call with an object containing matching files:

{
  './image/reveal_controller.js': { default: RevealController },
}

We can use a helper to register the controllers in our Stimulus application, which will infer the controller names from the file names by following the usual conventions.

import { Application } from 'stimulus'
import { registerControllers } from 'stimulus-vite-helpers'

const app = Application.start()

const controllers = import.meta.glob('./**/*_controller.js', { eager: true })
registerControllers(app, controllers)

app/frontend/controllers/index.js

  import '~/styles/background.css'
+ import '~/controllers'

  console.log('Vite ⚡️ Rails')

app/frontend/entrypoints/application.js

We can get the benefit of HMR by adding the vite-plugin-stimulus-hmr plugin to our vite.config.ts file.

  import { defineConfig } from 'vite'
  import RubyPlugin from 'vite-plugin-ruby'
+ import StimulusHMR from 'vite-plugin-stimulus-hmr'

  export default defineConfig({
    plugins: [
      RubyPlugin(),
+     StimulusHMR(),
    ],
  })

Now changes to our Stimulus controllers will be pushed instantly to the browser, allowing us to iterate as needed without reloading the page.

Sidecar assets

When using a library such as ViewComponent, it can be convenient to group JS and CSS files within each component folder—sometimes called sidecar assets.

Although there are a few options to achieve this, the simplest option is to import all JS files as we saw earlier with Stimulus controllers.

import.meta.glob('../components/**/*_component.js', { eager: true })

app/frontend/components.js

  import '~/styles/background.css'
+ import '~/components'

  console.log('Vite ⚡️ Rails')

app/frontend/entrypoints/application.js

Files matching the glob will be imported, as well as any of their dependencies, such as CSS files. For example, if we wanted to encapsulate a component using the Shadow DOM:

:host {
  display: flex;
  flex-direction: column;
}

.commenter {
  display: flex;
}

app/components/comment_component.css

import styles from './comment_component.css?inline'

class Comment extends HTMLElement {
  constructor() {
    super()
    const shadow = this.attachShadow({ mode: 'open' })
    shadow.innerHTML = `
      <style>
        ${styles}
      </style>
      <div class="commenter">
        <slot name="author"></slot>
      </div>
      <div class="body">
        <slot name="body"></slot>
      </div>
    `
  }
}
customElements.define('my-comment', Comment)

app/components/comment_component.js

Using a framework

Unlike other bundlers, adding a framework in Vite.js requires very little config. There are official plugins for Vue, React, and Svelte, which can be used to import .vue, .jsx, and .svelte files. For example, adding Vue support:

  import { defineConfig } from 'vite'
  import RubyPlugin from 'vite-plugin-ruby'
+ import VuePlugin from '@vitejs/plugin-vue'

  export default defineConfig({
    plugins: [
      RubyPlugin(),
+     VuePlugin(),
    ],
  })

We can now import .vue files and mount them as usual:

  import '~/styles/background.css'
+ import { createApp } from 'vue'  
+ import App from '~/components/App.vue' 
+  
+ createApp(App).mount('#app')

  console.log('Vite ⚡️ Rails')

As we saw earlier, Vite.js will detect changes we make in our components and push updates to the browser, causing Vue to re-render the updated components. To our delight this whole process happens within milliseconds 😃

Code-splitting

We can leverage glob and dynamic imports to split our bundle into separate files, which is useful to defer the load of components until they are needed.

Let's see an example using Inertia.js:

import { createInertiaApp } from '@inertiajs/inertia-vue'

const pages = import.meta.glob('../Pages/**/*.vue')

createInertiaApp({
  async resolve (name) {
    return await pages[`../Pages/${name}.vue`]()
  },
  ...

When using glob without eager: true, each value in the object is a function that returns a dynamic import for the corresponding module.

{
  '../Pages/Auth/Login.vue': () => import('/vite-dev/Pages/Auth/Login.vue'),
}

When building for production, each of the dynamic imports is bundled separately:

{
  '../Pages/Auth/Login.vue': () => import('./Login.3ee8f1b8.js'),
}

Additional Resources 📖

In this post we have barely scratched the surface of what's possible with Vite.js, but hopefully we saw enough to understand the basics and start using it.

The following links should be helpful if you would like to learn more, are looking for a starter template, or need a working example to use as a configuration reference.

Docs

• Vite.js and Vite Ruby Overview
• Vite.js
• Vite Ruby

Plugins

• Recommended Plugins for Ruby apps
• Rollup Plugins
• Awesome Vite

Example Apps

• Rails + Vite + React + Windi CSS
• Rails + Vite + Inertia.js + Vue2
• Stimulus + Vite

Starter Templates

• One-line Vite Ruby installer for Rails
• Rails + Vite Ruby + Windi CSS + Stimulus
• Jumpstart Rails + Vite + Stimulus

Until next time 👋🏼

In this post we will learn how to use this new API to turn a Vue component into a web component, how to package it as a library, and how to use it in plain HTML.

The complete source code for this example is available on GitHub.

Creating a Custom Element

The first step is to create a Vue component that we would like to use as a custom element. In this example, we will build a button that can toggle a dark theme on a website.

<script setup lang='ts'>
import { useDark, useToggle } from '@vueuse/core'

const isDark = useDark()
const toggleDark = useToggle(isDark)
</script>

<template>
  <button @click="toggleDark()">
    <span v-if="isDark">🌚</span>
    <span v-else>🌞</span>
  </button>
</template>

DarkModeSwitch.vue

Vue Component to Custom Element

Once we have our Vue component we can use the defineCustomElement API to create a custom element class that we can register.

import { defineCustomElement } from 'vue'
import VueDarkModeSwitch from './DarkModeSwitch.vue'

// Vue generates a new HTML element class from the component definition.
const DarkModeSwitch = defineCustomElement(VueDarkModeSwitch)

// Register the custom element so that it can be used as <dark-mode-switch>.
customElements.define('dark-mode-switch', DarkModeSwitch)

dark.ts

Styling the Shadow DOM 🎨

Custom elements defined using the Vue API always use a shadow DOM, so they are isolated from the parent document and any global styles in the app.

Styles for a custom element must be injected in its shadow root, which is why defineCustomElement can receive a styles option with CSS rules to inject.

const styles = ['button { font-size: 24px; ... }']
defineCustomElement({ ...VueDarkModeSwitch, styles })

Importing Components in Custom Element Mode

When importing a single-file component in custom element mode, any <style> tags in the component will be inlined during compilation as an array of CSS strings, allowing defineCustomElement to inject the styles in the shadow root.

Files ending in .ce.vue will be imported in custom element mode by default.

The customElement option can be used to specify which files should be imported in custom element mode (also available in vue-loader).

  plugins: [
    // Example: Import all Vue files in custom element mode.
    vue({ customElement: true }), // default: /\.ce\.vue$/
  ],

vite.config.ts

Caveats of Custom Element Mode 🚨

Warning: Only <style> tags in the single-file component will be inlined. Styles defined in nested Vue components won't be injected!

A possible workaround is to define and use all nested components as custom elements, but that prevents using Vue-only features such as scoped slots.

Please let me know if this changes in the future, and I'll update this note.

Adding styles to the single-file component

Now that styles in the component will be injected in the custom element, it's time to define how our toggle button should look.

<!-- Doesn't need to be scoped because it will be inside the Shadow DOM -->
<style>
/* Shadow Root: Properties can be overriden externally for customization */
:host {
  --color: #fbbf24;
  --bg-normal: #fAfAf9;
  --bg-active: #f5f5f4;
  --font-size: 24px;
}

button {
  background-color: var(--bg-normal);
  border: none;
  border-radius: .5rem;
  color: var(--color);
  cursor: pointer;
  display: flex;
  font-size: var(--font-size);
  overflow: hidden;
  padding: 0.4em;
  transition: background-color 0.3s ease,
    color 0.3s cubic-bezier(0.64, 0, 0.78, 0);
}

button:hover,
button:focus {
  background-color: var(--bg-active);
  outline: none;
}

span {
  width: 1.3em;
}
</style>

DarkModeSwitch.vue

Using a Custom Element

Once our custom element is registered, we can use it directly in HTML as we would with any of the built-in tags.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module" src="./dark.ts"></script>
  </head>
  <body>
    <dark-mode-switch></dark-mode-switch>
  </body>
</html>

Using Web Components in Vue

If we want to use these web components within Vue components, the only difference is that we need to hint the compiler to skip component resolution and treat them as native custom elements.

  plugins: [
    vue({
      template: {
        compilerOptions: {
          // Example: Treat all tags with a dash as custom elements.
          // i.e. dark-mode-switch
          isCustomElement: tag => tag.includes('-')

vite.config.ts

Packaging as a Library 📦

Vite.js provides a library mode which is a great way to bundle custom elements.

  build: {
    lib: {
      entry: resolvePath('index.ts'),
      name: 'DarkModeSwitch',
      fileName: format => `index.${format}.js`
    },

package/vite.config.ts

But, before we package our custom elements we need to make a few decisions:

• Should custom elements be eagerly registered?
• Should vue and other dependencies be bundled with the package?

Lazy Registration of Custom Elements

Usually, it's more flexible to export the custom element class, and provide a convenience method to register custom elements with default tag names.

import { defineCustomElement } from 'vue'
import VueDarkModeSwitch from './DarkModeSwitch.vue'

// Vue generates a new HTML element class from the component definition.
export const DarkModeSwitch = defineCustomElement(VueDarkModeSwitch)

// Optional: Provide an easy way to register the custom element.
export function register (tagName = 'dark-mode-switch') {
  customElements.define(tagName, DarkModeSwitch)
}

package/index.ts

That way we enable users to define the custom element using a different name.

import { DarkModeSwitch } from '@mussi/vue-custom-element-example'

customElements.define('toggle-dark-mode', DarkModeSwitch)

example registration

Externalizing dependencies

If we plan to use our component in applications that are already using Vue, then it's better to externalize it to prevent duplicates and ensure they use the same version.

In Vite.js this can be configured with build.rollupOptions.external.

  build: {
    rollupOptions: {
      // Externalize deps that shouldn't be bundled into the library.
      external: ['vue', '@vueuse/core'],
    },
  },

package/vite.config.ts

If custom elements will be used in non-Vue apps it might be suitable to bundle the dependencies instead, so that users don't have to provide them.

Farewell 👋🏼

Vue loves the open web, and the addition of defineCustomElement has made it easier than ever to create web components while enjoying an excellent DX.

It will be interesting to see future developments in this area, like being able to replace Vue with something lighter such as petite-vue for cases where the full runtime is not required.

The complete source code for this example is available on GitHub.

In this post I will cover a few ways to debug code inside Ruby gems in your application.

I'll use actionview in Rails as an example, but you can apply these techniques to debug any gem.

Debugging in Ruby 🐞

There are two main debugging styles in Ruby:

• Puts Debugging consists in adding puts statements in the target code, execute the script or application, and use the output to understand what's going on.

  def javascript_include_tag(*sources)
    puts "javascript_include_tag(#{sources.inspect})"

• Interactive Debugging enables pausing the program at a specific instruction, examining the current state in a REPL, and doing step-by-step execution.

  def javascript_include_tag(*sources)
    binding.pry # or binding.irb or byebug

One of many advantages of interactive debugging is that it becomes possible to easily navigate into a library's internals by using step or break.

To debug a library using puts debugging, you'll need to do things differently.

Opening Gems 💎⛏

You can run bundle open to open a gem in your favorite text editor.

The EDITOR environment variable will be used to infer the preferred text editor. I like using Sublime Text or Visual Studio Code to navigate the file tree.

For example, running bundle open actionview will open the version of the actionview gem specified in the nearest Gemfile.lock.

Editing In-Place ✍️

In contrast with compiled languages—where libraries are distributed as binaries—in Ruby most libraries are distributed as plain .rb files which are human-readable.

And human-writable! You can modify the code in a library, restart your app, and your changes will be picked up! 🤩

This is extremely useful when tracking down bugs—you can add puts or breakpoints as needed, or even modify the behavior of the library.

Interactive Debugging by hardcoding breakpoints inside actionview

Run gem pristine :library: once you are done to undo any changes. Otherwise, you risk relying on behavior that is local and unversioned 🙀

Using a Local Library 🔗

When you need to make extensive changes a nicer flow is to clone the library, and then point to your local copy.

For example, to fix a bug in actionview you would clone the Rails repo, open it in your editor to make changes, and then update the Gemfile in your project to specify the dependency using path.

# Assuming rails was cloned in the same parent directory
gem 'actionview', path: '../rails/actionview'

If a dependency is specified using a Git repository, prefer local paths in Bundler.

Just as in the previous section, it's important to restart the program you intend to debug after making changes.

Why is it necessary to restart the application? 🤔

Most Ruby programs use require to load a library into memory, and will use that cached version during their entire running time.

Restarting the program, such as a script or a web development server, ensures that any changes you have made to the library are loaded!

Additional Resources 📖

I hope this summary has been useful! A similar guide for JavaScript is available 😃

Please refer to the following documentation for more information:

• pry-byebug: Step-by-step debugging in Pry
• break: A debugger written in Ruby that integrates with IRB and Pry
• Debugging Cheat Sheet: Nice resource if you prefer puts debugging

In this post I'm going to cover a few techniques that you can use when debugging library-related issues in your Node.js applications.

I'll be using Vite.js as an example, as it provides an opportunity to cover some specifics related to debugging TypeScript packages and mono repos, but you can apply these techniques to debug any library.

Debug Output 📜

It's common for node.js packages to use the debug library to log information about their configuration, or operations they perform.

To enable logging for these libraries, set the DEBUG environment variable:

• DEBUG=* Enable all debug output
• DEBUG=vite:* Enable output for Vite.js core plugins
• DEBUG=vite-plugin-ruby:* Enable output for a specific plugin

Using a Debugger 🎯

Sometimes debug output is not enough to figure out what's the problem. Fortunately, there are many ways to start a debugging session.

Using node --inspect-brk will break execution until a debugger client is attached. You must provide a JS executable as an argument, for example:

• node --inspect-brk "$(npm bin)/vite"
• node --inspect-brk $(yarn bin vite)

Add an inspect shortcut in your scripts if you need to debug often.

I like to use the Node Inspector Manager extension, which will automatically attach the browser's DevTools to the node process.

DevTools provide a great debugging environment, with visual breakpoints, watchers, file navigation, and more. Visual Studio Code is another great option.

It's useful to ignore Node.js internals to avoid stepping into the framework.

Opening Packages 📖

In order to learn more and understand which files you should be debugging, you can run npm edit to open a package in your favorite text editor.

The EDITOR environment variable will be used to infer the preferred text editor. I like using Sublime Text or Visual Studio Code to navigate the file tree.

For example, running npm edit vite will open the copy of the vite package that is installed in the node_modules for the current directory.

Unlike the previous sections, this is something you can leverage for client-side packages as well.

Editing In-Place ✍️

Because JavaScript is a dynamic language, you can tweak the code in-place, restart the process, and your changes will be picked up.

Disclaimer: This has many caveats: bugs that only happen in your local, or the opposite, code that only seems to work in your local.

Skip to the next section for a better approach.

(I use it all the time though, so convenient 😅)

You can add console.log as needed, or even modify the behavior of the library, which can be useful to track down bugs.

In TypeScript packages (and some JS packages), make sure to edit the transpiled file instead of the sources. This is often dist/index.js but that depends on the library and target environment.

For example, in Vite.js the entrypoint is dist/node/index.js.

Using a Local Library 🔗

When fixing a bug or implementing features, a better flow is to clone the library, and then point to your local copy by using the npm link or yarn link commands.

Let's see a step by step example with vite:

# 1. Clone the repo
git clone git@github.com:vitejs/vite.git 
cd vite/packages/vite # Location of package.json
pnpm install

# 2. Make the local package available for linking
npm link # skip if using pnpm

# 3. Start compilation in "watch" mode
pnpm dev

In TypeScript or compiled JS libraries, it's important to build the library in order for changes to the source to be reflected in the linked project.

By convention, libraries define a build script to perform compilation, and a dev script that starts compilation in watch mode—file changes will start a new build.

Finally, link the library in the project you would like to test the changes:

# 4a. Link the library by name to use the local copy
npm link vite

# 4b. If using pnpm, link it by path instead
pnpm link ../vite/packages/vite

Just as in the previous section, it's important to restart the process you intend to debug after making changes.

Why is it necessary to restart? 🤔

Most processes will load the required libraries into memory, and then use these cached versions during their entire running time.

Restarting the relevant process, such as the Vite.js development server, ensures the updated version of the library is loaded.

Additional Resources 📖

I hope this summary has been useful! A similar guide for Ruby is available 😃

Please refer to the following documentation for more information:

• debug: Conventions and available filters
• Debugging Guide for node.js: CLI flags and inspector clients

In this post, we will cover a few practical usages of the singleton class as a way to modify the behavior of a particular object.

Adding Methods and Mixins

Since the singleton class of an object is specific to it, we can add methods to it, remove methods, or include modules, all without affecting other instances.

When calling a method on an object, Ruby will first look into its singleton class to find it, before traversing the rest of the method chain.

Defining Singleton Methods

Let's cover a few of the syntaxes we can use to define methods for a specific object.

person = Object.new

person.define_singleton_method(:name) {
  'Alice'
}

person.singleton_class.define_method(:to_s) {
  "#{ name } in #{ location }"
}

def person.location
  'Wonderland'
end

class << person
  def inspect
    "#{ to_s }: #{ super }"
  end
end

person.inspect # => "Alice in Wonderland: #<Object:0x00007fe7b5071238>"

The last two syntaxes should be familiar, we usually use them inside a class definition with self as the receiver (inside the class definition self is the class object).

These four different ways of defining a method are equivalent, each one is defining a singleton method.

A singleton method is a method defined in the singleton class of an object.

As we saw in the previous post, class methods are simply singleton methods of a class object, which explains why the same syntaxes can be used with a different receiver: they do the same thing.

Adding Mixins to the Singleton Class

We are not limited to adding or overriding methods, we can also work with modules.

module Greeting
  def introduce
    "Hey, I'm #{ name }"
  end
end

module NiceGreeting
  def introduce
    "#{ super }, nice to meet you!"
  end
end

person.extend(Greeting)
person.singleton_class.include(NiceGreeting)

person.introduce
# => "Hey, I'm Alice, nice to meet you!"

person.singleton_class.ancestors
# => [#<Class:#<Object:...>>, NiceGreeting, Greeting, ...

The example above illustrates how module inheritance works when dealing with the singleton class. Using extend is like including a module in the singleton class.

Calling extend on an object will make the module methods available on that object. In a class definition the object is implicit: the class object.

Practical Applications

Let's now dive into a few scenarios where all of this flexibility becomes useful.

Test Doubles and Method Stubbing

A test double is any object that stands in for a real object during a test. Some libraries allow to easily create doubles, and stub some of their methods:

book = instance_double('Book', pages: 236)
book.pages # => 236

A method stub is an instruction to an object to return a known value in response to a message:

allow(book).to receive(:title) { 'Free Play' }
book.title # => "Free Play"

Most libraries implement both of these features by leveraging the singleton class.

Let's see how we might be able to implement a very simplistic version of double, which returns an object that can respond to the specified methods:

def double(name, **method_stubs)
  Object.new.tap do |object|
    object.instance_variable_set('@name', name)
    method_stubs.each do |name, value|
      object.define_singleton_method(name) { value }
    end
  end
end

book = double('Book', pages: 236, title: 'Free Play')
book.pages # => 236
book.title # => "Free Play"

By using define_singleton_method we can create a test double that conforms to the provided options, without having to use temporary classes or structs, nor affecting other object instances.

RSpec Example Group Methods

When writing tests with RSpec, it's a good practice to keep helpers and state as local as possible. A typical way to do that is to include helpers only for certain types of tests.

RSpec.configure do |config|
  config.include(EmailSpec::Helpers, type: :controller)
end

Behind the scenes, RSpec will leverage the singleton class of a specific example group to include the module, without affecting other test scenarios.

RSpec.configure do |config|
  config.before(:each, type: :controller) do |example|
    example.example_group_instance.singleton_class.include(EmailSpec::Helpers)
  end
end

We can use this to our advantage as a way to define scenario-specific methods as well:

RSpec.configure do |config|
  config.before(:each, :as) do |example|
    example.example_group_instance.define_singleton_method(:current_user) {
      instance_exec(&example.metadata[:as])
    }
  end
end

RSpec.feature 'Visiting a page' do
  before { sign_in_as current_user }

  it 'can visit the page as a user', as: -> { User.first } do
    ...
  end

  it 'can visit the page as an admin', as: -> { Admin.first } do
    ...
  end
end

Check this example in the Capybara Test Helpers library, which uses it to inject test helpers using a :test_helpers option.

RSpec.feature 'Cities' do
  scenario 'adding a city', test_helpers: [:cities] do
    visit_page(:cities)
    cities.add(name: 'Minneapolis')
    cities.should.have_city('Minneapolis')
  end
end

Custom Cache Keys

When using Rails' cache, fetch_multi supports passing a list of keys, which will be yielded to the block in order to calculate the value to cache.

keys = items.map { |item| cache_key_for(item) }
Rails.cache.fetch_multi(*keys) { |key| value_for(key) }

What if we need the item instead of the key in order to calculate the value to cache?

items_by_cache_key = items.index_by { |item| cache_key_for(item) }
cache_keys = items_by_cache_key.keys
Rails.cache.fetch_multi(*cache_keys) { |key| value_for(items_by_cache_key[key]) }

Quite awkward. However, fetch_multi also supports passing a list of objects, in which case it will call cache_key on the objects to obtain the cache keys.

Rails.cache.fetch_multi(*items) { |item| value_for(item) }

But what if the items don't respond to cache_key?

We can leverage define_singleton_method to define it differently for each item:

items.each do |item|
  item.define_singleton_method(:cache_key) { cache_key_for(item) }
end
Rails.cache.fetch_multi(*items) { |item| value_for(item) }

Check this example in the oj_serializers library, which defines a cache_key singleton method for each object, so that they can be passed to fetch_multi.

Ad Hoc Validations in Rails

Let's imagine that we have a file upload API, and we are running an integrity check on save.

module FileIntegrityValidation
  extend ActiveSupport::Concern

  included do
    validate { errors.add(:file, 'is corrupt') if corrupt? }
  end

  def corrupt?
    ...
  end
end

What if we need to run the validation conditionally based on a setting that is not accesible from the model?

We can leverage the singleton class to define the validation conditionally:

class Api::FilesController < Api::BaseController
  resource(:file_upload)

  def create
    if check_file_integrity?
      file_upload.singleton_class.include(FileIntegrityValidation)
    end

    if file_upload.save
      ...

The resource syntax is coming from resourcerer.

In this case we can't use extend because ActiveSupport::Concern internally uses the included hook, which is only triggered when using include.

When using this pattern, it's better to encapsulate it so that it's easier to understand:

  def create
    if check_file_integrity?
      FileIntegrityValidation.apply_on(file_upload)
    end

module FileIntegrityValidation
  # Public: Define this validation only for the provided object.
  def self.apply_on(object)
    object.singleton_class.include(self)
  end
end

Summary

We can use an object's singleton class to define methods or include modules without affecting other instances, which enables very powerful techniques such as method stubbing and dynamically modifying behavior.

In practice, the use cases where this is necessary don't come around very often. It's usually possible to achieve what we need using simpler or more explicit strategies, that are easier to reason about.

As with most advanced techniques, you will know when you need it 😃

Let's begin by discussing the main purpose of metaclasses in Ruby.

Classes and Method Dispatching

In Ruby, everything is an object, and every object has a class, which defines the methods the object can respond to.

These two statements also apply to classes, which is what makes it possible for classes in Ruby to have their own instance variables and to receive methods.

class Animal
  @description = 'A multicellular eukaryotic organism.'

  def self.description
    @description
  end
end

Animal.description # => "A multicellular eukaryotic organism."

In contrast with other languages, in Ruby what we usually refer to as class methods are simply instance methods of a class object.

Now, if a class in Ruby is an object, and every object has a class which defines its methods, then a class in Ruby has a class which defines its methods.

Animal.class # => Class

If Class defined those methods, then they would be available for any class object.

Integer.description
# NoMethodError (undefined method `description' for Integer:Class)

How does Ruby pull it off then?

The Metaclass of a Class

Ruby deals with it by giving every object its own unique class, which defines the methods available for that object. Its very own metaclass.

The metaclass is called the singleton class because there is a single instance of it.

Animal.singleton_class # => #<Class:Animal>

This class is hidden in the inheritance chain (it doesn't show up when calling ancestors, and class returns Class), but we can think of it as the first ancestor when it comes to dispatching methods.

When calling a method on an object, Ruby will perform the method lookup by first checking on the object's metaclass, before traversing the rest of the method chain.

Animal.singleton_methods # => [:description]

Just like instance methods are defined in a class, class methods are defined in the metaclass of a class object.

This design enables Ruby to share the same dispatch mechanism for class methods: internally all methods are instance methods.

The Metaclass Hierarchy

In the diagram below we can see that each class has a corresponding metaclass, which is where their respective class methods are defined.

The inheritance chain of metaclasses is what allows to inherit and override class methods and call super.

And that is the main purpose of metaclasses in Ruby.

The Metaclass of an Object

Notice how the instance also has its own metaclass: classes are just a particular kind of object. When we call a method on an instance, Ruby will also look in its metaclass first.

Let's see a few examples of how we can use the metaclass to define methods that are specific to a particular instance.

animal = Animal.new
other_animal = Animal.new

class << animal
  def bark
    'Woof'
  end
end

def animal.greet
  'hi'
end

animal.define_singleton_method(:roar) { 'Rawr!' }

animal.bark  # => "Woof"
animal.greet # => "Hi"
animal.roar  # => "Rawr!"

animal.singleton_methods # => [:bark, :roar, :greet]
animal.singleton_class.instance_methods(false) # => [:bark, :roar, :greet]

other_animal.bark # NoMethodError (undefined method `bark' for #<Animal>)
other_animal.singleton_methods # => []

You will certainly recognize the first two patterns, they use the same syntax that is typically used with self to define class methods!

Once again, classes are just a particular kind of object. And yet, unlike classes, modifying the behavior of a particular object is rarely used in practice.

In the next post I share a few useful applications of this feature, read on!

Some advantages of using path helpers are:

• There's no need to take care of manually interpolating ids and parameters to build a String URL.
• Any change to the route definition affects the helper, so if a route is removed or modified, the path helper is no longer available.
• Code that uses an outdated path helper causes a runtime error, which can be detected by integration or unit tests, instead of rendering a path that would end up in a 404, like it would happen when using manual string interpolation.

Path Helpers in JS

Traditionally, frontend code in Rails replicates the path structure as defined in the backend, hardcoding the paths for every endpoint that needs to be accessed, and specifying HTTP verbs as needed (GET, POST, PATCH).

$.get('/search', { query })

This approach is very cumbersome, and it is possible to introduce typos, or make mistakes like choosing the wrong HTTP verb (PUT instead of PATCH, and so on).

We could avoid these problems if we had path helpers in JS.

While some tools that allowed to expose path helpers to JS already existed, they were created when sprockets was the way to compile frontend assets in Rails, long before the Webpack era.

I wanted a solution that provided an enjoyable front-end development experience. One that could leverage Webpack loaders and aliases, and was based on ES6 modules to allow tree-shaking, was easy to inspect, and where changes could be tracked under version control.

And that's why I created JsFromRoutes.

Shaping the Vision ✨

From a developer's UX perspective, the goal was to simplify how to make requests to a Rails API.

This meant not thinking about paths, parameter interpolation, nor HTTP verbs. Just plain function calls and promises.

import UsersRequests from '@requests/UsersRequests'

const user = await UsersRequests.create({ name, email })

These functions would be automatically generated from the Rails route definitions. The generation process should be transparent, and happen automatically as routes are added and the application is reloaded.

For maintainability, as well as for tree-shaking purposes, it was desirable to do a simple mapping: one request object per controller.

import { request } from '@services/ApiService'

export default {
  search: options =>
    request('get', '/users/search', options),

  create: options =>
    request('post', '/users', options),

  destroy: options =>
    request('delete', '/users/:id', options),
}

Delegating the actual request to an existing service would allow to keep the generated code lean. Any changes or improvements could then be made on the service itself, without having to regenerate the code. For example, switching from axios to redaxios, or to the fetch API.

Generating JS from Rails Routes ⚙️

Although the routes DSL in Rails wasn't designed for inspection purposes, it does provide the necessary metadata: the name of the endpoints, the HTTP verbs, and the paths including named parameters.

By doing some slight processing to the information in Rails.application.routes, and combining that with an ERB template, we are able to generate the JS functions we need.

import { request } from '@services/ApiService'

export default {
<% routes.each_with_index do |route, index| %>
  <%= route.helper %>: options =>
    request('<%= route.verb %>', '<%= route.path %>', options),
<% end %>
}

Automating the Flow 🤖

Why trigger the generation manually? Let the machines do it 😃

By adding a hook to Rails' reload process in development, we can automatically generate files from routes when a route is added, modified, or removed.

ActiveSupport::Reloader.to_prepare { JsFromRoutes.generate! }

In order to optimize file generation, we split the generated JS files by controller, and add a cache key based on the routes to avoid rewriting the file if the route definition hasn't changed.

When the Webpack development server is running, this automatically triggers a new build, and our request method or path helper is ready to be used!

The Gem 💎

The flow described above is now available through the js_from_routes gem. The library provides additional configuration options, visit the readme for more information.

This approach has similar benefits to path helpers in Rails:

• No need to manually specify the URL, preventing mistakes and saving development time.
• If an action is renamed or removed, the helper ceases to exist, which causes an error that is easier to detect than a 404.
• The HTTP verb is embedded in the helper, so it's transparent for the client code. Changing the verb in the route causes the JS code to be regenerated, no need to update the consumers!

Summary

js_from_routes allows to automatically generate path and API helpers from Rails route definitions, allowing you to save development effort and focus on the things that matter.

Since introducing this tool, we have saved a lot of time that we would have spent writing boilerplate code, avoided a lot of mistakes like typos and interpolation errors, and made the front-end development experience more enjoyable 😃

When starting to use Vuex, one quickly realizes that it's easier to manage and understand the state of a large application when the state is split between different modules in the Vuex store.

Unfortunately, working with modules involves using a namespace string to access state and getters, which makes typos hard to detect, and can quickly become cumbersome if using constants or a similar approach to avoid duplication.

Another weak spot is that dispatching actions feels very unnatural, and also requires specifying the namespace string as a prefix for the action name.

A smoother experience 🥃

The vuex-stores library helps you avoid these shortcomings by providing light wrappers around individual Vuex store modules, which I've dubbed "store-objects".

Store objects address these issues by allowing access to state and getters as properties, and dispatching actions easily by using plain method calls.

As a result, it's possible to leverage all the goodness in Vuex, using an elegant and convenient API.

Conventions 🔤

In order to organize these store objects, an approach that works nicely is to:

• Create one file per store module under a stores directory.
• Always use Store as a suffix for the file name (ModalsStore).
• Add a @stores webpack alias to make them convenient to import.

Let's take a look at an example usage:

<script>
import ModalsStore from '@stores/ModalsStore'

export default {
  name: 'ModalManager',
  computed: {
    // `mapState` and friends are available to inject state or getters into the
    // template, without the need to specify the namespace string.
    ...ModalsStore.mapState('modals'),
  },
  beforeMount () {
    // closeAllModals is an action, and it will be dispatched every time the
    // route changes, to hide any open modals.
    this.$router.afterEach(ModalsStore.closeAllModals)
  },
  methods: {
    // Actions are available as methods, notice the lack of boilerplate to
    // inject it in the component using `mapActions`.
    onModalClose (modal) {
      ModalsStore.removeModal(modal)
    },
    // NOTE: A shorter version would be `onModalClose: ModalsStore.removeModal`
  },
}
</script>

<template>
  <div class="modal-manager">
    <component
      :is="modal.component"
      v-for="modal in modals"
      :key="modal.id"
      v-bind="modal.attrs"
      @modal:close="onModalClose(modal)"
    />
  </div>
</template>

As seen in this short example, state, getters, and actions can be easily injected in a component using map helpers to make them available in the template.

Actions can be dispatched by simply calling a method, which is closer to how they are defined, and feels very natural. Typos in action names are prevented, since a method call would fail if the name is not correct (instead of being ignored)

The namespace string becomes an implementation detail which is transparent to the user, without having to use cumbersome manual techniques (such as constants) to avoid duplicating the module name all over the codebase.

Because incorrect ES6 imports provide clear errors, typos in the store name can be detected at compile time, and refactoring becomes a lot easier (usually as simple as search and replace).

There are more code samples available in the documentation 📖

Code Splitting ✂️

Store modules in Vuex can be registered dynamically, so internally vuex-stores leverages registerModule to add a new module when the store object is imported.

This means that store objects don't need to be imported up-front when initially defining the Vuex store, playing nicely with apps that do code splitting, since the code associated to a store object will only be loaded if needed.

As a result, the initial setup of the Vuex store will be lighter, and by using the conventions described above, code loading and execution will be optimized.

Summary

vuex-stores provides a simple way to work with Vuex modules by allowing you to define store objects to focus on one module at a time, making it more enjoyable to leverage Vuex.

The API is convenient and easy to learn, prevents mistakes such as typos, and works nicely when used in conjunction with ES6 modules, making the code easier to reason about and refactor.

Also, it's a lot of fun, give it a try! 😃

Documentation facilitates understanding, which is vital to enable change and continuous improvement.

How is it helpful? 🤔

Traditionally, we aim to produce clean and maintainable code to make it more reliable, and write tests to protect it. We use good variable names, split functions that perform too much into simpler ones, and design them so that parameter names convey enough information.

However, seeing what the code does is not the same as figuring out why it does it.

Most of the design process happens informally in chat rooms, conversations, and online documents. As a result, understanding a decision that was made a long time ago can be very time consuming, as it requires scanning through chat messages, and reaching out to the people that were involved.

When we are not able to obtain enough information about these decisions, it becomes harder to effectively reason about the software, slowing down fixes and improvements.

This is why learning about past decisions should be as efficient and straightforward as possible: it will save us a lot of time and frustration down the line. Knowing the context will allow us to make informed decisions, which are better decisions.

If you haven't started, the best time is now ⌛

If we are to make our software easier to understand, and thus easier to change, we should document our intent in every possible way. Think about it as a byproduct of the thought process we carry out as developers when designing a solution and writing code.

Capture any breadcrumbs that might be useful in the future to find out how things are supposed to work, helping other developers unravel the conditions and mindset that influenced the code, even when we no longer remember why.

Document as you go. No other time will be better to document than when the ideas are fresh in our mind. Memories fade over time, and what we fail to record then might be hopeless or painfully time-consuming to remember later.

The overhead of documenting on the spot is negligible, but the overall benefits are certainly not!

Documenting is intrinsically a valuable activity 💰

To get the best out of it, we should imagine we are someone else trying to understand our work. Which things will not be so obvious a few months from now? Thinking about it can help to reveal our underlying assumptions and knowledge.

Is it clear how this component interacts with other parts of the system?

By doing this mental exercise, we will be able to find simpler and more readable ways to solve a problem, allowing us to refine our designs and solutions. It has a direct positive impact in maintainability, regardless of whether someone actually reads the resulting documentation.

Our focus should be on recording intent, why and how things should happen. It's also useful to cross-reference classes and objects that interact with each other. Aim for the bigger picture, and work your way down as needed.

A lightweight approach is good enough ⚡

In practice, we've found that using a conventional but minimal syntax for comments works well, and that it's better to inline documentation in the code itself.

# Public: Abbreviation of a few words that sums up what the question is about.
# Example: 'Side Effects'
field :title, type: String

Inline docs are always at hand, require very low effort to add and update, and are very helpful for developers to gain insight (both during reviews and in the long run).

They should be clear and concise. Don't overstate the obvious and remove any words that feel unnecessary. Creating good documentation takes practice, it's more about writing skills and less about programming.

While it's possible to generate documentation pages from a minimal syntax, usually navigating through the source code and reading the inline docs is more convenient. Using Goto Symbol or Goto Definition on any editor does the trick.

Won't the comments become outdated really quickly? 🙀

Version control to the rescue! 🦸

More often than not, the core concepts in the software we write rarely change, so the documentation tends to be useful even when not entirely accurate.

Combined with source control, even when the comments are outdated, the original intention is never lost. We can navigate back through history and get the full context in which the documentation was written.

In the same way we should document our intent in methods, properties, and classes, it's also important to capture the broader purpose of changes in commits. This will enable us to look back to learn more, saving us an invaluable amount of time when trying to understand past decisions.

As a result, we can move forward with deeper undestanding and confidence, refactoring or removing code without fear of accidentally breaking the app, or going against an otherwise long-forgotten decision.

Pull Requests as the unit of change 🧩

Usually in a team environment, the pull request replaces the commit as the unit of change. Besides providing a platform for code review, pull requests are great for adding rich non-text information, such as images and video, and hyperlinks to external resources.

As a result, they also have an immense potential for communication and documentation. We should leverage the description to explain substantial changes (why and what for), provide screenshots, and any content that makes it easier to follow the work.

Doing so will leave a solid trail that can help anyone grasp the full picture later on, in addition to improving the communication and quality of the reviews. Two for one!

TL'DR: Document all the things! ✏️ 📖

Code is read a lot more often than it's written, which is why inline docs provide a great return for their tiny cost. Same can be said about writing a nice pull request description, describing specific decisions in comments, and providing screenshots.

We've saved a lot of time when figuring out how things work, enabled our team to refactor with confidence, prevented problems and regressions, and made entire areas of the app more approachable for other developers.

The simple practice of documenting helps junior and senior developers alike, and after you start using it, you'll be wondering why you didn't start sooner 😃

Keywords in Method Parameters

Just like the splat operator (*args) captures any parameters as an Array of arguments, the double-splat operator (**attrs) captures any option parameters as a Hash.

The nice thing is that it allows to destructure a Hash argument into any of its individual keys, and mark it as required, or make it optional and provide a default value for it.

def greet(first_name:, last_name: nil, **attrs)
  name = [first_name, attrs[:middle_name], last_name].compact.join(' ')
  puts "Hi #{ name }!"
end

greet(first_name: 'Gale')
# Hi Gale!

greet(last_name: 'John')
# ArgumentError (missing keyword: first_name)

greet(first_name: 'Bruce', middle_name: 'Wayne', last_name: 'Keaton')
# Hi Bruce Wayne Keaton!

There's one big gotcha which comes up a lot when first learning Ruby:

def greet(**attrs)
  puts "Hi #{ attrs[:name] }!"
end

greet
# Hi !

greet('name' => 'Jane')
# ArgumentError (wrong number of arguments (given 1, expected 0))

Many developers have scratched their heads wondering what's going on, until they learn the cause of this unintuitive message.

Only Symbol keys are allowed in keyword arguments 😲

Ruby handles keyword arguments differently in its internals, which unfortunately leaks into this error message.

Merging Hashes with the Double-Splat operator

The double-splat operator can also be used to combine hashes. The order matters, when resolving duplicate keys, the rightmost ones will take priority.

jane = { :first_name => "Jane", :last_name => "Doe" }

{ **jane, :last_name => "Johnson" }
# { :first_name => "Jane", :last_name => "Johnson" }

{ :last_name => "Johnson", **jane }
# { :last_name => "Doe, :first_name => "Jane" }

There are a few caveats when combining hashes:

• It does not combine keys of different types, such as String and Symbol.
• It can only be used with Hashes where all keys are Symbols.

jane = { :first_name => "Jane", :last_name => "Doe" }
{ **jane, "first_name" => "John" }
# { :first_name => "Jane", :last_name=>"Doe", "first_name"=>"John" }

jane = { "first_name" => "Jane", "last_name" => "Doe" }
doe = { **jane, first_name: "John" }
# TypeError (hash key "first_name" is not a Symbol)

This message used to be very cryptic like the one for keyword arguments, but it has improved a lot since the feature was first added 🎉

A quick note about Rails

When using Rails a developer might think:

I can obtain values from params using Symbol keys, but I can't pass them as keyword arguments! Thought they were all Symbol keys?

The short answer is no. In Rails controllers, params is an instance of HashWithIndiferentAccess. You may index it with Symbol keys but internally it uses String keys.

Fortunately, symbolize_keys is our friend here, allowing us to transform any Hash, such as HTTP parameters, to something we can pass as keyword arguments.

Summary

So there you have it, ** is to Hash what * is to Array, and is a very convenient tool to write shorter, expressive code.

Just watch out for errors when using non-Symbol keys in keyword arguments, at least until Ruby improves that error message 😉

In our team, we always use trailing commas when defining multi-line literals for arrays and hash (object in JS) literals.

It's great that both Ruby and JS allow this in their syntax, because as a result we are able to get cleaner diffs:

Notice how the same code change results in a drastically simpler diff: adding or removing an item changes a single line, nothing more.

Other Benefits 👩‍💻👨‍💻

Reordering lines, or sorting them alphabetically with the help of an editor (like Sublime Text), will always result in valid code, without the need to manually add the missing comma to avoid a syntax error.

Also, conflicts in source control are less likely to happen, since each line change becomes independent, unlike the usual approach where we are actually removing the last line without a comma to add two lines.

Finally, tools like git blame are more likely to display relevant commit information, rather than the commit that added the comma.

Automation 🤖

To make this practice effortless, we have modified the configuration of the static analysis tools (Rubocop and ESLint), to require trailing commas in multi-line literals.

We have also set up Guard to listen for file changes and automatically run the tools with --autofix, so that commas are automatically added when we forget; we don't really need to think about it.

In ESLint for JS:

  "comma-dangle": ["error", "always-multiline"],

In Rubocop for Ruby:

Style/TrailingCommaInArrayLiteral:
  EnforcedStyleForMultiline: comma

Style/TrailingCommaInHashLiteral:
  EnforcedStyleForMultiline: comma

Style/TrailingCommaInArguments:
  EnforcedStyleForMultiline: comma

An example Guardfile configuration:

# Run Rubocop every time we change a file, and autofix it if possible.
guard :rubocop, all_on_start: false, cli: ['-a'] do
  ...

Summary

Using trailing commas in multi-line literals results in code that is syntactically more stable to changes, and keeps a cleaner history in source control.

Developers make less syntax errors, since they can add and remove items, sort or reorder them, without having to manage missing (or extra) trailing commas.

We've been using this approach for years now, and haven't run into any issues in practice. It's been great so far 😃

In this post we'll talk about settingslogic and its design decisions, how they affect reliability, and how we can overcome them.

Even if you are not familiar with these libraries, reading this article might help you to learn about potentially harmful practices, and how to avoid them in your own code.

Settingslogic

Settingslogic can read a .yml file and turn it into a Ruby object, which provides access to settings by indexing it as a Hash, or by using method calls.

Settings can be modified

The library aims to be flexible, by allowing to create a setting that is not present in the file or modify an existing one, by using:

Settings['property'] ||= 'value'

Although it might seem like a good idea, this behavior introduces uncertainty about whether a setting will be available or not when accessing it, and the value it might have, since that depends on the execution order of the program.

Because the library is not thread-safe, modifying settings makes them suceptible to race conditions in multi-threaded apps or multi-threaded app containers.

Values are mutable

Even when not creating or modifying a setting at runtime, the values read from the .yml file can be accidentally modified since the settings are not frozen (specially String, Hash, and Array values).

For example, when working with a Hash or Array setting, calling merge! or push causes the setting to be changed on every subsequent access, which can have unpredictable consequences in the application.

These accidental mutations are usually very hard to detect, and can cause bugs that are difficult to replicate and track down.

Writing code carefully to avoid mutating the data structures is not enough, since we have no guarantee that third-party libraries will be as careful. To solve this we would need to always clone settings before handing them over, which is cumbersome and error-prone.

Limited to a single file

Only one .yml file can be specified, so there's no way to read configuration from multiple files. Because settings are necessary to run the application, it's important that the file is versioned under source control.

In our case, this meant that when developers changed a setting based on their local setup, or to perform a manual test, they had to manually skip it when making a commit.

As a result, many times a developer would accidentally push these changes that should not be merged upstream, and we had to be on the lookout during code reviews to prevent unwanted changes.

Error-prone design

These problems we experienced with settingslogic, related with reliability and collaboration, are a consequence of the design decisions in the library.

The library defaults are troublesome, such as deferring the load of the .yml file until the settings are accessed, making it possible for an app to start successfully and fail later at runtime.

In the end, it has the same disadvantages of simpler approaches, like using a plain OpenStruct to manage settings.

A Better Way

With that in mind, we decided to design a new solution from scratch, that could handle these shortcomings, and actively prevent bugs and misusage.

The result is BetterSettings, designed after the following concerns:

• Predictability: Once created, settings can not be added or modified, which prevents race conditions and makes usage safe and predictable.
• Immutability: All setting values are frozen, preventing an entire category of bugs related to accidental mutation.
• Multiple sources: Settings can be read from different files. This allows to split settings as needed, or create additional files for development purposes.
• Better errors: Accessing a missing setting is treated as an error, helping developers to easily detect typos and other mistakes with a clear error message.
• Fail-fast: Source files should be eager loaded by default, so that problems in the environment are detected during deployment.

The setup for the .yml file is very similar to settingslogic, you can find more information and examples in the README.

How does it work?

Internally, settings are stored in a frozen Hash, which is an instance variable in the BetterSettings object. We delegate to_h to this internal hash for easy access, but other than that, we don't expose any Hash methods.

We go through every hash entry, processing any nested Array and Hash objects, freezing every wrapped value, setting it in an instance variable, and making it accessible by defining a getter for that key.

It's worth noting that we wrap nested Hash values in instances of your BetterSettings class, which will recursively repeat the process.

As a result, the entire settings graph is readable but immutable, and each nested object exposes getters for the available keys.

To make errors a bit friendlier, we implement method_missing to provide context on where a setting is missing, instead of an unhelpful NoMethodError.

Finally, we sprinkle some syntax sugar by making every top-level key available as a method in the Settings class, by delegating it to a root_settings instance that is populated when calling source in the class.

Reading from multiple files ⚙

Not being limited to a single source file opens up the possiblities.

We usually read two optional files: development.yml and test.yml that are loaded in the development and test environments respectively, allowing each developer to easily override settings in their local setup.

In a Rails app with the typical setup, the configuration looks like this:

class Settings < BetterSettings
  source Rails.root.join('config/application.yml'), namespace: Rails.env

  if Rails.env.development?
    source Rails.root.join('config/development.yml'), namespace: Rails.env, optional: true
  end

  if Rails.env.test?
    source Rails.root.join('config/test.yml'), namespace: Rails.env, optional: true
  end
end

Having a development.yml file comes in handy when making changes that should not be shared, such as a temporary change to test a different configuration, or a permanent one that is only relevant in a specific local setup (such as different host names or port numbers).

This could also be achieved by reading environment variables (see the next section), but for development using an optional file is more convenient, as it's located in the same folder than the main one, and settings can be copied and tweaked.

On the other hand, test.yml makes it possible to configure tests to run with a different formatter for the results, or configure optional behavior, like automatically opening the screenshots that are captured when integration tests fail.

This flexibility enables us to provide awesome defaults, while still allowing everyone to modify the configuration according to their personal preference or local setup, without having to worry about pushing those changes by accident.

Environment Variables

In server environments, such as staging and production, we use environment variables for any sensitive information, such as passwords.

In order to ensure that missing environment variables are quickly detected, we use this simple helper:

module Env
  # Public: Read an environment variable by name.
  # NOTE: Defaults are only used in the development and test environments.
  def self.require(*args, &block)
    if Rails.env.development? || Rails.env.test?
      ENV.fetch(*args, &block)
    else
      ENV.fetch(args.first)
    end
  end
end

and then in application.yml:

mailer: <%= Env.require('MAILER_PORT', 587) %>

By using this helper, we can be very strict on servers－where we need everything to be configured (such as hosts, ports, and third-party integrations)－and lenient in development－where we can just provide a default value and then override it by using development.yml if necessary.

We prefer this pattern over using ENV.fetch with a default value as a fallback, since that would cover up a missing environment variable in the servers.

Summary

So there you have it, BetterSettings is a settings solution for Ruby apps that encourages good practices, is friendlier for team collaboration and source-control, and prevents bugs.

BetterSettings: simple, immutable, better.

While they might be similar in terms of operations and transactions, different domains will often use different jargon, and as a result, prefer different names for a given feature or aspect of an application.

For example, a concept that in our application is "person", might be referred to as "user", "customer", or "employee", based on the language of their specific domain, or when using their in-house terminology.

Using the same terms than our users in their every day routine can help to make the software feel more natural and easier to grasp, lowering the adoption barrier and reducing the resistance to change in large organizations.

...fits right in with our usual flow.

Using i18n fallbacks 🌎

Fortunately, we can easily accomplish this by leveraging the existing i18n tools that are available in most platforms.

Just like we might allow a customer to switch between American or British variants of the English language (en-US and en-UK), we can create additional language-variants or locales for each customer or domain (en-LAW):

en-LAW
  customer: client

We can then use i18n fallbacks, so that any keys that are not defined in our domain-specific locale fall back to the usual definition in the language.

In the example above, any users that have the LAW translation preset assigned would see "client", but other users might see "customer".

This allows us to achieve a nice balance between configurability and productivity.

By managing these text overrides within the translation engine, it becomes almost effortless to dynamically customize the language used in the app.

Dictionaries for different domains or specific customers can be added with ease, and it becomes easier to test all the different combinations in the application.

A solution for Ruby apps 💎

I have wrapped a Ruby solution as the i18n_multitenant gem. Please check the readme for a more thorough explanation of how language variants are used, and a few examples on how to organize translations in order to effectively implement the approach.

What about translations in the browser?

For single-page applications or other apps where it's desirable to perform the translations in the browser, we can use a library such as i18n-js.

It's possible to configure it to use fallbacks, allowing us to reuse the same translation files in the JS world.

Summary

i18n fallbacks provide a simple way to adapt the terminology used in our software based on different domains and users needs, making it feel more familiar and easier to use without restricting the software's flexibility.

Product.collection.aggregate [
  { '$match' => { 'country' => 'US' } },
  { '$project' => { 'categories' => 1, 'price' => 1 } },
  { '$unwind' => '$category_ids' },
  {
    '$group' => {
      '_id' => '$category_ids',
      'avg_price' => { '$avg' => '$price' }
    }
  },
  { '$sort' => { 'avg_price' => -1 } },
  { '$limit' => 30 }
]

Turns out Origin—the gem that powers Mongoid's query DSL—already provides methods for each aggregation operation. The only problem is that it doesn't provide a way to execute the aggregation, and there's no documentation about it 😬

Every aggregation method call adds an operation to an internal pipeline, which we can manually retrieve by calling the pipeline method:

products = Product.where(country: :US).
  project(categories: 1, price: 1).
  unwind('$category_ids').
  group(_id: '$category_ids', :avg_price.avg => '$price').
  desc(:avg_price).
  limit(30)

products.pipeline
# {"$match"=>{"country"=>:US}}
# {"$project"=>{"categories"=>1, "price"=>1}}
# {"$unwind"=>"$category_ids"}
# {"$group"=>{"_id"=>"$category_ids", "avg_price"=>{"$avg"=>"$price"}}}
# {"$sort"=>{"avg_price"=>-1}}
# {"$limit"=>30}

Notice how using the DSL we obtain the same aggregation pipeline that we have in the first example, except it's way more concise, and we are able to use Symbol extensions like avg, max, or add_to_set, which add a great deal of expressiveness and make our queries more concise.

Now all we have to do is pass the pipeline to the aggregate method:

Product.collection.aggregate products.pipeline

We can add a little syntax sugar using refinements and make it even more convenient:

module AggregationRefinements
  refine Mongoid::Criteria do
    def aggregate
      collection.aggregate pipeline
    end
  end
end

using AggregationRefinements

Product.project(categories: 1, price: 1).
  unwind('$category_ids').
  group(_id: '$category_ids', :avg_price.avg => '$price').
  aggregate

Or if you are using query objects, it's as simple as adding a method to the objects where you need to perform aggregations:

def aggregate
  queryable.collection.aggregate(queryable.pipeline)
end

Now we can enjoy Mongoid's fluent DSL for aggregations 😃

Let's look at a simple example to understand how we might use class variables:

class Animal
  @@animals = []

  def self.all
    @@animals
  end

  def other_species
    @@animals - [self.class]
  end
end

class Dog < Animal
  @@animals << self
end

class Cat < Animal
  @@animals << self
end

Animal.all
# [Dog, Cat]

Cat.new.other_species
# [Dog]

Dog.new.other_species
# [Cat]

The @@animals class variable is shared among subclasses, and we can refer to it by using the same syntax from both class and instance methods.

Limitations of Class Variables

Now, what happens if we wanted to do something different, like storing metadata or configuration in each subclass?

class Animal
  @@sound = '?'

  def talk
    @@sound
  end
end

class Dog < Animal
  @@sound = 'woof!'
end

class Cat < Animal
  @@sound = 'meow!'
end

Dog.new.talk
# "meow!"

Cat.new.talk
# "meow!"

Because class variables are shared between the parent class and its subclasses, the value of @@sound gets stepped over by the last subclass, rather than it taking a different value for each subclass as intended.

Class Instance Variables

Fortunately, there's a simple way to achieve this in Ruby:

class Animal
  def self.sound
    @sound
  end

  def talk
    self.class.sound
  end
end

class Dog < Animal
  @sound = 'woof!'
end

class Cat < Animal
  @sound = 'meow!'
end

Dog.new.talk
# 'woof!'

Cat.new.talk
# 'meow!'

By using instance variables, each subclass gets its own variable so @sound does not get stepped over, and each subclass can configure the variable as needed. So, how does it work?

Classes in Ruby are plain objects, instances of the Class class.

Let that sink in for a bit 😄

Because each class is an object, it can have instance variables just like any other Ruby object.

Although they are often called class instance variables to differentiate them from actual class variables, there's nothing special about them—they are just plain ole' instance variables.

The key practical difference is that class variables (@@) are shared among a class and all of its descendants, whereas class instance variables (@) are not shared and each class has separate instance variables just like you would expect from different objects.

Limitations of Class Instance Variables

It's worth noting that in the last example we lost the convenience of referencing the @sound variable directly on the talk method like we did in the second example, and instead need to define a getter method at the class level in order to access it.

This is because the same syntax is used for regular instance variables, so we can only refer to class instance variables directly when we are in the class scope—like in class methods and in the top-level context of a class definition.

Also, since we can't use class instance variables to share values between a class and its descendants, in cases where we would like to access the variable of a parent class we will need to refer to it using a fully qualified getter (such as Animal.sound) or use metaprogramming in order to achieve that.

Driving it home 🏠 🚗

In general, class instance variables are the way to go because they are not shared, which is very useful when building libraries or DSLs, and we don't run the risk of the value getting stepped over by accident in a subclass.

On the other hand, when the variable must be shared by a class and its descendants we should always use class variables.

When inheritance is not in play we can use either, but it's better to be consistent and pick a "default". I always use class instance variables unless I actually need the variable to be shared.

We should now be less fuzzy on what @ means when used in class methods or in a class definition, and when to use class instance variables instead of class variables 😃

As we learned, each time a watcher is created Angular will add the expression to a watch list, which is then iterated during each digest cycle to evaluate every expression and detect changes. That means, the more watchers are registered, the more Angular has to process during the digest cycle.

In pages that have many components—such as long lists and grids—the amount of watchers can be very high, which can negatively affect the performance of our app and make it feel unresponsive.

In this post we will take a look at two techniques that can help us mitigate this problem and speed up our applications.

One-Time Bindings

One of the most convenient techniques that we have to reduce the amount of watchers is the use of one-time bindings. Any expression that starts with :: is considered a one-time expression.

<div ng-repeat="user in ::users">
  <h1>{{{ ::user.name }}</h1>
</div>

Angular will remove a one-time expression from the watch list once it has been resolved, unlike normal expressions which are evaluated on every digest cycle.

If the expression will not change once set, it is a candidate for one-time binding. For example, internationalization 🇬🇧 🇪🇸

As a result, we have less expressions being watched, which makes the digest loop faster, increases the responsiveness of the app, and allows more information to be displayed at the same time.

Using one-time bindings is an easy and effective way to reduce the amount of watchers, but there's a catch. Angular won't detect changes on each digest cycle and update the view, which makes them only suitable for values that won't change.

Recompiling with Events

What about expressions with a value that might change, yet remain the same most of the time? It's a waste to evaluate them on every digest cycle, but we can't just use one-time expressions since the value might eventually change.

A technique that I have been using in pages where performance is critical is event-driven recompilation.

<h1 recompile-on="user:changed">{{ ::user.name }}</h1>

This technique has three key aspects: one-time expressions, compilation, and event propagation. Let's see how the recompileOn directive could be written:

# Public: Recompiles an element if an event occurs.
#
# NOTE: Do not use in combination with ng-if or ng-repeat, unless a one-time
# binding is used in the expression.
app.directive 'recompileOn', ($compile) ->
  directive =
    scope: true
    priority: 5
    restrict: 'A'
    compile: (element) ->
      html = element[0].outerHTML

      (scope, element, attrs) ->
        # Internal: Will trigger a recompilation if the event is triggered.
        recompileOnEvent = (eventName) ->
          scope.$on eventName, (e) ->
            # Remove the previously added listener, if any.
            removeListener?()

            # Replace the element after the digest loop that triggered the event has ended.
            scope.$evalAsync ->
              newEl = $compile(html)(scope.$parent)
              element.replaceWith(newEl)

              # Destroy the old scope, since a new one was created by using compile.
              scope.$destroy()

        removeListener = recompileOnEvent(attrs.recompileOn)

The directive will listen for a particular event on the current scope, and force a recompilation of the element when the event is triggered. This means that every directive inside the element will be processed from scratch, including our one-time expressions.

Events can be triggered as usual:

$scope.$broadcast('user:changed')

Conclusion

One-time bindings provide a very efficient way to render dynamic values once without taking up watchers, while $on and $compile provide a helpful way to render from scratch when we need to. This combination works very well for complex pages where the amount of watchers is taking a toll on performance.

There are many variations that we can introduce to the implementation of recompileOn, such as allowing to pass several event names, or checking the event arguments for a specific value, such as an id. We can take this idea as far as we want to 🚀

As with any optimization, it's important to consider whether the performance improvement justifies the additional complexity. Use it wisely!

Bindings and Watchers

One of the most useful features in AngularJS are data-bindings, which allow us to bind a model or property to a view; whenever the model changes, the view is updated automatically.

<input ng-model="user.name" type="text" />
<h1>{{ user.name }}</h1>

How does that work? When you write an expression like {{ user.name }}, Angular creates a watcher that observes the user.name property, which will be triggered whenever the model changes, allowing Angular to update the view content.

We can also create watchers manually and execute arbitrary code when the model changes:

$scope.$watch('user.name', function(newName, oldName) {
  console.log('user.name changed from', oldName, 'to', newName);
});

The first argument passed to $watch is known as the model, and the second argument is the listener function, which is called whenever the model (or more precisely, value of the watched expression) changes.

Now that we know what watchers can do for us, let's dig a bit deeper and learn how they work. How does Angular figure out when user.name changed in order to call the listener?

The Watch List and Dirty Checking

Each time a watcher is created, Angular adds the expression to a watch list to track changes. Angular will walk down the watch list from time to time and resolve each watcher through a process called dirty checking:

• Keep the last value for each watched expression.
• Evaluate the expression: if the value is the same than the last one continue down the watch list.
• If the value is different the expression is dirty, so propagate the change by calling each listener with the old and the new value.
• Once the change has been synchronized across the app, replace the last value with the new value.
• Continue to the next expression in the watch list.

For every UI element that is bound to a $scope object, a watch is created and added to the watch list, which is checked on every digest loop.

🔁 The Digest Cycle

And it's in the $digest cycle where every watcher in the watch list is evaluated, and the changes propagated to the listeners.

This cycle starts as a result of a call to $scope.$digest(), which often happens as a result of an action performed by the user. For example, clicking an element with the ng-click directive will explicitly call $scope.$digest() and start the loop.

Once the cycle starts, it will go through the watch list, propagating changes to listeners as needed.

There are many Angular directives and services that will automatically trigger a digest cycle, such as ng-model and $timeout.

👑 Keep Calm and Digest

Once Angular has run through the entire watch list, if any value changed, it will start a new digest cycle until no model is changed and no watchers are triggered.

Why does it run the loop all over again? Because any $watch listener could change the value of an expression that was evaluated earlier in the digest loop, so Angular wouldn't be able to detect and propagate that change.

Remember that Angular uses dirty-checking as a way to determine if the watched expression changed, so the only way to guarantee all changes are propagated is to go through the watch list again and check that no values were changed during the previous digest cycle.

This means that the digest loop will run a minimum of two times, even when listeners don’t change any models.

Minimize changes to watched models when inside listener functions, each change could trigger an extra digest loop.

If the loop runs ten times or more, Angular will throw an exception to prevent a possible infinite loop, which would make the app unusable.

Conclusion

Because of the nature of Angular's internals, it's very important to minimize the amount of watchers in order to keep the digest cycle fast.

At the same time, it's important to ensure that our application doesn't trigger more digest cycles than necessary, since each loop requires evaluating every watcher in the list.

While watchers are a very useful feature, the digest cycle implementation takes a brute force approach, which makes it almost magical at times, but is inefficient and can cause performance problems in complex applications.

In the next post, we will take a look at some techniques that help to reduce the amount of watchers and improve the performance of our app. Stay tuned! 😃

Then(/^I should see a "(.*?)" comment$/) do |message|
  expect(page).to have_css('li.comment', text: message)
end

Then(/^I should not see a "(.*?)" comment$/) do |message|
  expect(page).not_to have_css('li.comment', text: message)
end

Not only is it boring to write steps like this: it also has the downside of introducing duplication into our test steps. If the DOM changes, we are forced to update both steps.

Even worse, if the DOM changes and we forget to update the negative assertion, it will always pass since the element doesn't even exist!

Let's give it another shot, but this time we will encapsulate the DOM references:

def have_comment(message)
  have_css('li.comment', text: message)
end

Then(/^I should see a "(.*?)" comment$/) do |message|
  expect(page).to have_comment(message)
end

Then(/^I should not see a "(.*?)" comment$/) do |message|
  expect(page).not_to have_comment(message)
end

The code is easier to read, and we solved a potential maintainability issue, nice! It's possible to add a little touch of regular expressions to combine both steps into one:

Then(/^I should( not)? see a "(.*?)" comment$/) do |should_not, message|
  if should_not
    expect(page).not_to have_comment(message)
  else
    expect(page).to have_comment(message)
  end
end

If we write "should not see" then the group will match and the should_not variable will contain " not". If we write "should see" then the group won't capture anything and should_not will be nil. This allows us to make a simple conditional check.

We can leverage Ruby's expressiveness and take it a bit further:

Then(/^I should( not)? see a "(.*?)" comment$/) do |should_not, message|
  expect(page).send (should_not ? :not_to : :to), have_comment(message)
end

Shorter, but not necessarily easier to understand. Fortunately, we can create our own custom RSpec matcher to encapsulate this pattern and make it easier to reuse and understand:

# features/support/to_or.rb
module PositiveNegativeExpectationHandler
  def to_or(not_to, matcher, message=nil, &block)
    if not_to
      not_to(matcher, message, &block)
    else
      to(matcher, message, &block)
    end
  end
end

RSpec::Expectations::ExpectationTarget.send(:include, PositiveNegativeExpectationHandler)

Finally, we are able to express the step in a very concise and readable way:

Then(/^I should( not)? see a "(.*?)" comment$/) do |not_to, message|
  expect(page).to_or not_to, have_comment(message)
end

No magic here 🎩, just clever naming 🐰

to_or has been a very helpful addition to our projects, allowing us to write simple steps that read like English.

You can copy the PositiveNegativeExpectationHandler to a support file in your project, like features/support/to_or.rb, and start using it right away 😃

rails-ajax_redirect is an extension to this unobtrusive behaviour that adds AJAX support to redirect_to. It allows us to redirect an AJAX request as usual, instead of having to perform the redirect by handling the response manually in JS every time.

This is helpful in many different scenarios, and just like remote: true, it allows us to skip some of the boilerplate in cases where we need to redirect the user to a different page.

Rails::AjaxRedirect extends redirect_to to use a custom status code for ajax requests, while still setting the Location header. On the front-end, it adds a handler for the ajax:success event, that navigates to the location in the header for responses that have the custom status code.

This makes it possible to write a simple redirect as usual, but without having to handle it manually every time 😃

Turbolinks

If your application uses Turbolinks check out turbolinks-redirect, on which rails-ajax_redirect is based on. The advantage is that it will perform faster navigation by leveraging Turbolinks to visit the new location.

Axios

If your application makes the AJAX request using axios instead of jQuery, it will be necessary to add an interceptor similar to this:

axios.interceptors.response.use(
  response => {
    if (response.status === AJAX_REDIRECT_STATUS_CODE) {
      window.location = response.headers.location
    }
    return response
  },
  error => Promise.reject(error),
)

A big part of the library though, focuses on creating a type-safe builder for creating view hierarchies, as an alternative to the XML-inflated view approach. Some of the benefits of defining a layout with Anko are type-safety, and efficiency, since it's not necessary to parse the XML.

I decided to take the DSL for a test drive by rewriting the "Navigation Drawer Activity" template from AndroidStudio, replacing some of the XML layouts with the Anko DSL.

We can define an AnkoComponent to create the UI:

package com.maximomussini.anko

import android.support.design.widget.AppBarLayout
import android.support.design.widget.Snackbar
import android.support.v4.content.ContextCompat
import android.support.v4.view.GravityCompat
import android.util.TypedValue
import android.view.Gravity
import android.view.View
import com.maximomussini.anko.util.snackbar
import org.jetbrains.anko.*
import org.jetbrains.anko.appcompat.v7.toolbar
import org.jetbrains.anko.design.appBarLayout
import org.jetbrains.anko.design.coordinatorLayout
import org.jetbrains.anko.design.floatingActionButton
import org.jetbrains.anko.design.navigationView
import org.jetbrains.anko.support.v4._DrawerLayout
import org.jetbrains.anko.support.v4.drawerLayout

class MainUI : AnkoComponent<MainActivity> {

    override fun createView(ui: AnkoContext<MainActivity>): View = with(ui) {
        drawerLayout {
            id = R.id.drawer
            fitsSystemWindows = true
            createAppBar(ui)
            createNavigationView(ui)
        }
    }

    fun _DrawerLayout.createAppBar(ui: AnkoContext<MainActivity>) {
        coordinatorLayout {
            fitsSystemWindows = true

            appBarLayout {
                toolbar {
                    id = R.id.toolbar
                    popupTheme = R.style.AppTheme_PopupOverlay
                    backgroundResource = R.color.colorPrimary
                }.lparams(width = matchParent) {
                    val tv = TypedValue()
                    if (ui.owner.theme.resolveAttribute(R.attr.actionBarSize, tv, true)) {
                        height = TypedValue.complexToDimensionPixelSize(tv.data, resources.displayMetrics);
                    }
                }
            }.lparams(width = matchParent)

            relativeLayout {
                horizontalPadding = resources.getDimensionPixelSize(R.dimen.activity_horizontal_margin)
                verticalPadding = resources.getDimensionPixelSize(R.dimen.activity_vertical_margin)
                textView("Hello World!")
            }.lparams(width = matchParent, height = matchParent) {
                behavior = AppBarLayout.ScrollingViewBehavior()
            }

            floatingActionButton {
                imageResource = android.R.drawable.ic_dialog_email
                backgroundColor = ContextCompat.getColor(ui.owner, R.color.colorAccent)
                onClick {
                    snackbar("Replace with your own action", Snackbar.LENGTH_LONG) {
                        setAction("Action") { ui.toast("Clicked Snack") }
                    }
                }
            }.lparams {
                margin = resources.getDimensionPixelSize(R.dimen.fab_margin)
                gravity = Gravity.BOTTOM or GravityCompat.END
            }
        }.lparams(width = matchParent, height = matchParent)
    }

    fun _DrawerLayout.createNavigationView(ui: AnkoContext<MainActivity>) {
        navigationView {
            fitsSystemWindows = true
            setNavigationItemSelectedListener(ui.owner)
            inflateHeaderView(R.layout.nav_header_main)
            inflateMenu(R.menu.activity_main_drawer)
        }.lparams(height = matchParent, gravity = GravityCompat.START)
    }
}

And then, use the component to set the content view for the activity instead of using an XML layout:

package com.maximomussini.anko

import android.os.Bundle
import android.support.design.widget.NavigationView
import android.support.v4.view.GravityCompat
import android.support.v4.widget.DrawerLayout
import android.support.v7.app.ActionBarDrawerToggle
import android.support.v7.app.AppCompatActivity
import android.support.v7.widget.Toolbar
import android.view.Menu
import android.view.MenuItem
import org.jetbrains.anko.find
import org.jetbrains.anko.setContentView
import org.jetbrains.anko.toast

class MainActivity : AppCompatActivity(), NavigationView.OnNavigationItemSelectedListener {

    lateinit var drawer: DrawerLayout

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        MainUI().setContentView(this)
        drawer = find<DrawerLayout>(R.id.drawer)

        val toolbar = find<Toolbar>(R.id.toolbar)
        setSupportActionBar(toolbar)

        val toggle = ActionBarDrawerToggle(this, drawer, toolbar,
                R.string.navigation_drawer_open, R.string.navigation_drawer_close)
        drawer.setDrawerListener(toggle)
        toggle.syncState()
    }

    override fun onBackPressed() {
        if (drawer.isDrawerOpen(GravityCompat.START)) {
            drawer.closeDrawer(GravityCompat.START)
        } else {
            super.onBackPressed()
        }
    }

    override fun onCreateOptionsMenu(menu: Menu): Boolean {
        menuInflater.inflate(R.menu.main, menu)
        return true
    }

    override fun onOptionsItemSelected(item: MenuItem): Boolean {
        when (item.itemId) {
            R.id.action_settings -> {
                toast("Settings")
                return true
            }
        }
        return super.onOptionsItemSelected(item)
    }

    override fun onNavigationItemSelected(item: MenuItem): Boolean {
        when (item.itemId) {
            R.id.nav_camera -> toast("Camera")
            R.id.nav_gallery -> toast("Gallery")
            R.id.nav_slideshow -> toast("Slideshow")
            R.id.nav_manage -> toast("Manage")
            R.id.nav_share -> toast("Share")
            R.id.nav_send -> toast("Send")
        }
        drawer.closeDrawer(GravityCompat.START)
        return true
    }
}

In contrast with the generated version, the Anko version does require some boilerplate to set dimensions and colors from resources, but has a lot of expressiveness when it comes to bindings. Notice how it's not necessary to create references to most of the components, since the listeners are added to each view when they are instantiated:

floatingActionButton {
    onClick { snackbar("FAB", Snackbar.LENGTH_LONG) }
}

Compare this to the usual code, which incurs in the cost of finding the view (even if it's a very low cost) and referencing the view id:

val fab:FloatingActionButton = findViewById(R.id.fab) as FloatingActionButton
fab.setOnClickListener {
  Snackbar.make(it, "FAB", Snackbar.LENGTH_LONG).show()
}

The Anko DSL exposes the native API of each View, so it's only possible to do what Android components can do, with the exception of a few synthetic properties to set text or an image from a resource.

Unfortunately, that means things get pretty rough once we dive into styling and theming. The Android SDK and support libraries contain a lot of hacks that rely on the view being created by a LayoutInflater from the XML, initializing the view with a Context and an AttributeSet. There's no first-class support for setting the style or theme programmatically, which means it's not possible to set them when using Anko either.

Anko does provide a way to style a view, but it leaves much to be desired since it requires targeting the different view classes manually, unlike styling in XML where valid attributes are applied automatically.

When it comes to theming, Android uses ContextThemeWrapper internally to override getTheme for a view or its children. Since the current Anko version does not allow to override the context used to create a view inside the DSL, using a theme-wrapped context manually is extremely contrived.

No theming support is a serious limitation, since most components in the design library need a theme to be styled properly.

It should be possible to add support for theming in Anko, but unfortunately theming is just one of many XML-based hacks and workarounds in the SDK.

Adding views with Java code is very cumbersome, so most Java developers will stick to XML, and the SDK and support library will continue to do hacks around XML inflation.

The idea behind the Anko DSL is a very interesting one, but it seems like the Android SDK is not polished enough for Anko to reach its full potential.

In the frontend this has become increasingly more common because of all the available languages that compile to JavaScript. CoffeeScript was one of the first ones to gain adoption, but nowadays we have a myriad of available languages like Elm, ClojureScript, Opal, and many more.

Recently, we were trying to debug a strange issue with one of my coworkers, where we had a list of selectable items with a checkbox to select/unselect all the items. Selecting all the items was working properly, but only the first item got unselected.

After debugging it for a while we reached the conclusion that the iteration was being interrupted. Could lodash have such a serious bug?

selectAll = (isSelected) ->
  _.each tasks, (task) -> task.selected = isSelected

Fortunately, we decided to skip that theory, and instead reached for the documentation, which stated:

Iteratee functions may exit iteration early by explicitly returning false.

Which sounds like a reasonable feature that can help to create more efficient algorithms—though we weren't returning false!

But CoffeeScript was. The language draws inspiration from Ruby, and it borrows features like expressions and implicit returns. For functions, this means that the last executed expression becomes the return value of the function. This allows us to write very concise functions:

isEven = (n) -> n % 2 == 0

If we reinterpret our snippet above taking implicit returns into account, it is equivalent to:

function selectAll(isSelected) {
  return _.each(tasks, function(task) { return task.selected = isSelected })
}

When we unselect all the items and selectAll(false) is called, the first iteration returns the value of task.selected which is false, causing lodash to exit the iteration. Mistery solved 🔍

We can fix the bug by explicitly returning null or true on each loop, which will avoid stopping the iteration, and all the items will be unselected correctly.

selectAll = (isSelected) ->
  _.each tasks, (task) ->
    task.selected = isSelected
    true

These are two useful features on their own, yet extremely inconvenient when combined. The reason is that the library was written for a language with a different mindset. The design of the language and the design of the library are not fully compatible.

TL;DR

Watch out for language differences when using libraries written for another language, they will bite sooner or later.

Let's take a look at how we can improve our Git usage in bash by adding a few plugins 💻

Bash Git Autocompletion

A great way to get Git autocompletion is to install the bash-completion package. This plugin will improve our experience when switching or pulling different branches, and is a real time-saver when using topic branches.

Installation on OS X

First, install bash-completion using Homebrew:

brew install bash-completion

and then add this line to ~/.bash_profile to load the plugin:

[[ -f "$(brew --prefix)/etc/bash_completion" ]] && source "$(brew --prefix)/etc/bash_completion"

Installation on Ubuntu

sudo apt-get install bash-completion

Bash Git Prompt

Running a Git command without knowing the current branch is like running rm or mkdir in the terminal without knowning the current directory: it's dangerous and error-prone.

Sure, we could type pwd every time before running those commands, but it wouldn't be practical. Why not take the same approach for Git, and display the current branch in the terminal prompt?

bash-git-prompt is a project that takes care of that, displaying the current branch and other helpful stats. It has many different themes available, which can be customized by specifying a theme through the GIT_PROMPT_THEME environment variable.

Installation on OS X

First, install bash-git-prompt using Homebrew:

brew install bash-git-prompt

And then source the file in your ~/.bash_profile as follows:

[[ -f "$(brew --prefix)/opt/bash-git-prompt/share/gitprompt.sh" ]] && source "$(brew --prefix)/opt/bash-git-prompt/share/gitprompt.sh"

Installation on Ubuntu

It might be necessary to clone the project's git repo, and source gitprompt.sh into the ~/.bashrc file.

Basic Customization

The following are some settings I modified in my ~/.bash_profile:

GIT_PROMPT_ONLY_IN_REPO=1 # Use the default prompt when not in a git repo.
GIT_PROMPT_FETCH_REMOTE_STATUS=0 # Avoid fetching remote status
GIT_PROMPT_SHOW_UPSTREAM=0 # Don't display upstream tracking branch
GIT_SHOW_UNTRACKED_FILES=no # Don't count untracked files (no, normal, all)

These constants must be defined before sourcing bash-git-prompt in the ~/.bash_profile or ~/.bashrc file.

Customizing the Git Prompt

The themes that come bundled with bash-git-prompt displayed too much information for my taste, and the symbols in the default theme are not particularly meaningful.

After trying different themes, I decided to bake my own. I wanted something that emphasized the important bits and pieces, looked clean, and was easy to understand. Fortunately, the plugin provides a command to generate a custom theme file:

git_prompt_make_custom_theme Default

The command creates a ~/.git-prompt-colors.sh based on the default theme and will get loaded by the plugin automatically, so you can start playing with the variables right away. However, you may need to dive into the source code to figure out how each variable is used, and find the ones you want to customize.

After tweaking the variables for a while, I was able to create a custom theme. The expresiveness of emojis made it easier for me to understand the current git status 😅

# .git-prompt-colors.sh

override_git_prompt_colors() {
  GIT_PROMPT_THEME_NAME="Custom"

  PathShort="\W" # Display only the current folder

  # Display the current folder first
  GIT_PROMPT_START_USER="${Green}${PathShort}"
  GIT_PROMPT_START_ROOT="${Green}${PathShort}"

  # Skip the default prefix
  GIT_PROMPT_PREFIX="${ResetColor}"

  # Use whitespace as separator
  GIT_PROMPT_SEPARATOR=" "

  # Skip remote branch
  GIT_PROMPT_REMOTE="${ResetColor}"
  GIT_PROMPT_UPSTREAM="${ResetColor}"

  # Use yellow for the current branch
  GIT_PROMPT_BRANCH="${Yellow}"

  # Use red and green for behind and ahead origin
  GIT_PROMPT_SYMBOLS_BEHIND="${Red} ↓"
  GIT_PROMPT_SYMBOLS_AHEAD="${Green} ↑"

  # Add a few emojis to make it fun!
  GIT_PROMPT_STAGED="${Yellow}👍 "
  GIT_PROMPT_CONFLICTS="${Red}❌ "
  GIT_PROMPT_CHANGED="${Yellow}✏️ "
  GIT_PROMPT_UNTRACKED="❔ "
  GIT_PROMPT_STASHED="${Yellow}📦 " # A lot nicer than the default flag
  GIT_PROMPT_CLEAN="${ResetColor}✅ "  
  GIT_PROMPT_SYMBOLS_NO_REMOTE_TRACKING=" 🔒 " # when a branch is untracked

  # Skip the default suffix
  GIT_PROMPT_SUFFIX=" "

  # Skip the default ending
  GIT_PROMPT_END_USER="${ResetColor}"
  GIT_PROMPT_END_ROOT="${ResetColor}"
}

reload_git_prompt_colors "Custom"

Emojis are a great way to make ye olde terminal a bit more fun! 🎉

It would be awesome if bash-git-prompt provided a way to customize the full prompt order and displayed elements, with a template string like:

GIT_PROMPT="{PathShort}{Branch}{Remote}{Modified}{Staged}{Clean}"

That would make it possible to create very different themes, as well as opting out of certain information—like git stashes.

For now, I'm pleased with the result; it's practical, looks nice, and I don't need to type git branch to check the current branch 😎

'Jane Jim Jenny'.split.map { |s| s.length }.reduce { |sum, n| sum + n }
# => 12

When performing this kind of functional transformation, it's tedious to write a block to perform a simple method call. An extremely common idiom in Ruby uses symbols to specify the method that should be called:

names.map(&:length).reduce(&:+)

Sweet! 🍰

In Ruby, the ampersand operator & can coerce an object into a Proc by calling the to_proc method if it's defined. More generally, &object will be evaluated in the following way:

• object is a Proc: & converts it to a block.
• object is not a Proc: & tries to call to_proc on the object, and then converts it to a block.

names.map &:to_s
# is the same than
names.map &:to_s.to_proc

Huh? 😕

It turns out the magic is in how Ruby defines to_proc for symbols. In recent versions of Ruby, the method is defined in C, but it would look like this in Ruby:

class Symbol
  def to_proc
    ->(obj, args = nil) { obj.send(self, *args) }
  end
end

Back to our snippet, let's expand the to_proc call incrementally until we arrive at the same block we would write by hand:

names.map &:to_s

# We can expand it to
names.map &:to_s.to_proc

# Replacing "to_proc" with the result of calling the method
names.map &->(name, args = nil) { name.send(:to_s, *args) }

# "map" passes a single argument to the block, so we can simplify
names.map &->(name) { name.send(:to_s) }

# Calling the method directly we get
names.map &->(name) { name.to_s }

# Since "&" transforms Procs and Lambdas to blocks, it's equivalent to
names.map { |name| name.to_s }

So there you have it, & will coerce the :to_s symbol by calling to_proc, and then transform the resulting proc or lambda to a block.

There's nothing special about the shorthand &:method syntax. Ruby arbitrarily defines Symbol#to_proc in a way that allows programmers to avoid some boilerplate.

A world of proc 🌎

Now that we understand what is really going on, we could use to_proc for our own benefit by defining it in our objects and classes.

require 'ostruct'

class Formula
  def initialize(formula)
    @formula = formula.gsub('^', '**')
  end

  def apply(variables)
    OpenStruct.new(variables).instance_eval(@formula)
  end

  def to_proc
    ->(*args){ apply(*args) }
  end
end

x2 = Formula.new('x^2 + y^2')
[{ x: 1, y: 1 }, { x: 3, y: 4 }, { x: 5, y: 7 }].map(&x2)
# => [2, 25, 74]

We may also define to_proc at the class level, allowing us to pass a class as a block:

class Formula

  def self.to_proc
    ->(*args){ new(*args) }
  end
end

['x^2 + y^2', 'x + y^3'].map(&Formula)
# => [#<Formula @formula="x**2 + y**2">, #<Formula: @formula="x + y**3">]

A note on performance 📊

Running some benchmarks in Ruby 2.2.3, it seems that there is not an important performance penalty from using to_proc. I wrote a small benchmark that you can run if you are curious 😃

Summary

There's nothing special about the shorthand &:method syntax. Ruby defines Symbol#to_proc in a particular way that allows programmers to avoid some boilerplate, and the & operator can coerce any object into a block by calling to_proc.

Symbol#to_proc is so ubiquitous that there's no harm in using it; most of the times it can help to keep the code terse without any downsides.

However, it's better to stay away from to_proc in everyday usage, since it is as obscure as it is powerful. Defining to_proc for custom objects can make it very difficult to reason about the code, which defeats the purpose of using it in the first place.

A while ago I was working on a feature that required displaying information from several mongodb collections. The performance was pretty bad, since for each item being displayed it was necessary to traverse nested and polymorphic associations to get the rest of the data.

Although Mongoid provides eager loading support out of the box, it has a few limitations:

• No Nested: Only direct relations can be eager loaded.
• No Polymorphic: Polymorphic relations can't be included.
• Criteria-only: It's only possible to use eager loading with a Mongoid::Criteria object. We can't leverage the functionality if we have a list of objects.

Unfortunately, one of those traversed associations was both nested & polymorphic, so in the beginning the only available solution was to eager load the relations manually.

After thinking about it for a while, I decided to give it a shot and come up with an extension to eager load polymorphic and nested associations, and do away with all the boilerplate that is necessary to perform eager loading.

Mongoid::Includes 💎

When writing the library, I picked a few constraints in order to give the project a clear direction:

• Reuse Mongoid's eager loading functionality as building blocks.
• Fail-fast, or as early as possible.
• Cover only the most common use cases.
• Allow to override eager loading for the not so common ones.

Choosing these constraints allowed me to keep the library fairly small, without compromising its usefulness in more complex scenarios.

The result is mongoid_includes, a gem that enhances support for eager loading in Mongoid, allowing to include polymorphic and nested associations, and modify eager loading queries on the fly.

Album.includes(:songs).includes(:musicians, from: :band)

Band.includes(:albums, with: ->(albums) { albums.gt(release: 1970).limit(2) })

Mongoid::Includes extends the includes method to support polymorphic associations without any syntax change. For nested includes, it expects a :from option, indicating from which relation the include is going to be performed, eager loading it as well.

While those are the most typical cases, it also supports a :with option which conveniently allows to modify the default query, and a :loader option which receives the foreign keys of the documents to include.

Polymorphic or nested includes might be a sign of a poorly designed schema. mongoid_includes is very easy to use, but it should only be used if it's truly necessary.

Extending Mongoid

Although it was possible to reuse the eager loading logic in Mongoid, doing so required a lot of fiddling and monkey-patching (using prepend), since the library does not provide any point of extension.

Mongoid's eager loading was written to work with queries, and assumes that the included documents will match an association on the model, so it relies on the association metadata to perform the includes. There is no simple way to reuse the logic without using relation metadata.

The biggest downside though, is that there is no way to perform eager loading for a set of documents, since the code relies on the contract of Mongoid::Criteria. We can't use eager loading if we triggered the query by using any Enumerable method, or got the models by aggregation or any in-memory operation 😥

It would be a lot easier to extend Mongoid's functionality if it had a more modular design. Adding support for plugins that can be attached to the query lifecycle would be a huge step in that direction—less patching means more and better extensions.

A Better Way

Some ORMs take a very different approach when it comes to eager loading. Ecto, a popular database wrapper for the Elixir language, has a different philosophy:

NOTE: Ecto does not lazy load associations. While lazily loading associations may sound convenient at first, in the long run it becomes a source of confusion and performance issues.

As a long time Mongoid user, I can painfully relate to this statement. N+1 queries are one of the fastest ways to degrade performance, and lazy loading associations makes it a lot easier to introduce them by accident. By not implementing lazy loading, the library becomes a lot simpler, and it encourages good practices and efficient data access patterns 🍹

Ecto also allows you to modify which models will be included for an association—like the :with option in mongoid_includes—and you can also preload associations on a given model or models after they have been fetched from the database using the Repo.preload/2 method. So much win!

Playing with Ecto inspired me to keep looking for a better solution for eager loading in Mongoid. Mongoid::Includes solves the first two limitations, but wouldn't it be great if we could preload documents without a query? 😉

A performance issue that is very common when using ORMs is the N+1 query problem. This anti-pattern usually occurs when trying to load related information for each item in a list of results.

Since most ORMs don't perform eager loading by default (to avoid fetching more data than necessary), it's necessary to make extra queries per item to fetch the related data. Imagine that we have a simple music store app:

class Band
  include Mongoid::Document
  has_many :albums
end

class Album
  include Mongoid::Document
  belongs_to :band
  has_many :songs
end

class Song
  include Mongoid::Document
  belongs_to :album
end

A classic appearance of the N+1 problem would be:

albums = Album.where(year: 1970)

albums.each do |album|
  puts "Album: #{album.name}, Band: #{album.band.name}"
end

In this example, we are loading a list of albums (the first query) and then loading the related band for each album, making one query per album. With a list of N albums, we make 1 query to get the albums and N queries to get the bands: a total of N+1 queries.

The problem can also appear in other scenarios, such as more complex object graph traversals. In those cases, it can be much harder to spot the cause.

To understand why this is inefficient, we need to consider the impact of latency in the response time. Even if each of the N queries is executed quickly, each query requires one database round trip. This latency will add up linearly as N increases, which can have a devastating effect in the response time.

Avoiding the N+1 problem

A solution to the N+1 problem is to eagerly load the documents that we need, so that when we access a relation it's already preloaded and doesn't trigger a query.

In Mongoid, we can do this by running an $in query using the relation foreign keys to fetch all the related records, and then assign the relations in memory using set_relation. This way, we only perform a single query to fetch a relation, regardless of the amount of documents returned by the first query.

band_ids = albums.map(&:band_id)

bands = Band.in(id: band_ids)

bands = bands.index_by(&:id)
albums.each do |album|
  album.set_relation(:band, bands[album.band_id])
end

The algorithm changes slightly depending on the type of relation we want to include, and how the foreign keys are stored, but the idea is the same: get a list of foreign keys, use them to make a query to fetch the related documents, and assign the relations in memory using the foreign keys to match the objects.

album_ids = albums.map(&:id)

songs = Song.in(album_id: album_ids)

album_songs = songs.group_by(&:album_id)
albums.each do |album|
  album.set_relation(:songs, album_songs[album.id])
end

Although eager loading the documents manually is not very complex, writing this logic every time is cumbersome, error-prone, and hard to maintain.

Fortunately, Mongoid has baked-in support to eager load relations using the includes method, which allows to specify all the relations that we want to eager load once the query is made. The following is equivalent to the two snippets above:

albums.includes(:band, :songs)

Easy, right? This becomes extremely useful when trying to avoid those sneaky N+1 queries we were talking about 😉

Performance Considerations

Although eager loading can be helpful, it's important to be aware that:

• It takes a lot of processing to obtain the foreign keys, fetch the documents from the database, traverse them, and assign them to the objects in memory.
• $in queries are usually slower, and get slower as the amount of values increases.

Most of the times, the overhead of processing in memory and making a more complex query is lower than the latency of issuing a lot of queries separately. Rewriting the code to eager load the relations that we need will usually improve the performance.

As with any performance optimization, there might be some corner cases where eager loading is slower. It's important to run benchmarks and measure the response time to verify that it's worth it to use eager loading 📊

Always keep an eye out for this anti-pattern; accessing the database in a naive way will hurt the performance. Using a tool like bullet can help to detect N+1 queries or unused includes, but it's better to use it as a safety net for the cases that slipped past our manual control.

Have in mind that in mongodb it's possible to embed the related documents instead of storing them in separate collections. Depending on the domain requirements, it can be a very good way to get the best out of the database, and avoid the problem entirely.

Thinking about data access from the beginning yields the best results, because it allow us to spot potential inefficiencies, and find alternative queries that perform better.

Limitations in Mongoid

Eager loading in Mongoid has some limitations:

• Criteria-only: It's only possible to use eager loading with a Mongoid::Criteria object. We can't leverage the functionality if we have a list of objects.
• No Nested: Only direct relations can be included, nested relations can't be eagerly loaded (like band.albums.songs).
• No Polymorphic: Polymorphic relations can't be included.

The first limitation exists because Mongoid relies on the metadata to pick the appropriate eager loading algorithm. The relation metadata allows to infer things like foreign key names, the name of the database collection, and the name of the setter method for the relation.

I have solved the other limitations in mongoid_includes 💎, which extends the includes method to support eager loading polymorphic and nested associations.

You can check the next post where I talk about this gem and explain the motivation behind it, as well as the difficulties of extending Mongoid 😃

In addition, it will handle the hierarchy in queries, by allowing to query the parent class to return documents from any subclass, or query a specific subclass to fetch only documents of that specific type. In order to do this efficiently, Mongoid will check for existing indexes that contain _type as a prefix, or add a { _type: 1 } index.

As a consequence of the approach:

• Storage size increases since we need to store an additional attribute on every document. The smaller the document, the bigger the impact of this extra field.
• For large collections, adding a _type index or prefix it to existing ones to create compound indexes could be a concern, since large indexes might not fit in memory, which would quickly degrade the performance.

Bah, trade-offs. It's still awesome 😏

While this behaviour is usually desirable, there are some scenarios where it's suitable to use inheritance in Ruby but it doesn't make sense to store different classes of the hierarchy in the same collection.

In particular, if subclasses will always be queried independently, we can store each type in a different collection, which will improve the performance because it:

• Doesn't require additional indexes.
• Doesn't require extra information in each document.
• Provides a natural way to partition the data.

Easy. Just use mixins to share code between the subclasses, Mongoid will store them in separate collections 😌

An example (more like "A Very Contrived Example" 😄)

Let's imagine that we have a drawing app, where you can draw many triangles on a canvas, and need to choose between three different drawing modes: regular, equilateral, or isosceles.

class Triangle
  include Mongoid::Document
  ...
end

class IsoscelesTriangle < Triangle
  validate_two_sides_are_equal
end

class EquilateralTriangle < Triangle
  validate_all_sides_are_equal
end

We can take advantage of this restriction and store each type of triangle in a separate collection, which will prevent the database from scanning more documents than necessary to execute our queries.

This will be more efficient than adding an extra _type attribute and index, which is the default behaviour provided by Mongoid when inheriting a model. If we want to make this work, we will need to avoid Mongoid's single-collection inheritance.

Mixins

Using mixins to share the code is a nice way to get the job done, but in this case it falls short because Triangle (the base class) is not abstract—turning it into a module wouldn't allow us to instantiate it. We can deal with this by creating a module that contains the code that we want to reuse.

We shall name it Trianglable. Hmm, sounds weird, let's go with Trilateral. Maybe BaseTriangle? Triangleness? Damn, names are tough 😫

module AbstractTriangle
  include Mongoid::Document
  ...
end

class Triangle
  include AbstractTriangle
end

class IsoscelesTriangle
  include AbstractTriangle
  validate_two_sides_are_equal
end

class EquilateralTriangle
  include AbstractTriangle
  validate_all_sides_are_equal
end

Much better 😐

Using Inheritance

In cases like this I would like to start with inheritance, which can make the code easier to follow, and move to the mixin approach or composition as the requirements change and some of the behaviour or logic in the base class should no longer be shared with the subclasses.

When facing a similar situation recently, I decided to take a look at Mongoid internals and find out if it was viable to prevent the unwanted STI behaviour. Ideally, we would get standard Ruby inheritance, without the subclass being handled differently by Mongoid.

The first thing to do, was to look for an inherited hook in one of the many modules inside the library, which happened to be in Mongoid::Traversable. Unfortunately, there's a lot going on in that method; Mongoid doesn't make it easy to extend or modify its functionality in a clean way.

Feeling determined, I chose to hack my way into a solution. The result is the module below—hacky at best, more likely a problem waiting for the next Mongoid update to blow up 🙉

module Mongoid

  # Public: Allows to use inheritance to reuse logic, without using Single-
  # Collection Inheritance, storing the model and superclass in different
  # collections.
  module NoHeritage
    extend ActiveSupport::Concern

    included do
      # Internal: Preserve the default storage options instead of storing in
      # the same collection than the superclass.
      delegate :storage_options, to: :class
    end

    module ClassMethods
      # Internal: Prevent adding _type in query selectors, and adding an index
      # for _type.
      def hereditary?
        false
      end

      # Internal: Prevent Mongoid from defining a _type getter and setter.
      def field(name, options = {})
        super unless name.to_sym == :_type
      end

      # Internal: Preserve the default storage options instead of storing in
      # the same collection than the superclass.
      def inherited(subclass)
        super

        def subclass.storage_options
          @storage_options ||= storage_options_defaults
        end
      end
    end
  end
end

All things considered, it provided a nice balance between sharing code, keeping the storage and index size down, and maintaining a straightforward structure in the code.

¯\(ツ)/¯

This is related with other ideas like lean manufacturing: focus all effort in the things that add value, and reduce everything else. This management philosophy was started by Toyota in the ’50s and later evolved to a business methodology called lean thinking, a way to apply the idea—of delivering more value while eliminating waste—to business in general.

While both lesscode and the lean methodologies share the idea of creating something valuable and cutting down the waste, lesscode has a deeper emotional perspective. As a developer, you are responsible for any complexity in the solution.

It's by embracing the constraints—both natural and self-imposed, such as aiming for a great design—and gaining a sense of minimalism, that one is able to discover elegant and simple solutions, and find freedom.

Freedom from bloated frameworks, cargo-cult programming, and the fear of not understanding. Freedom to rid your code out of excess and complexity, and focus on what matters.