F. Knüssel

Configuring and using Sublime Text in 2026

2026-04-03T00:00:00Z

I wanted to share (and mostly document for future me) my Sublime Text setup for a Turborepo monorepo running TypeScript, React, Next.js, CSS modules and Biome.

This is the second time I write about Sublime Text. As I said in my first post, I've been a Sublime Text user for the longest time and I still enjoy using it. It's very fast and supports most of the features I need every day. It's also as minimalist as it gets and, after years of daily use, the keyboard shortcuts are muscle memory at this point.

1) Package control

If not already installed, go to Tools > Install Package Control. This is the extension marketplace equivalent.

2) Core packages

Open the command palette (Cmd+Shift+P), run Package Control: Install Package, and install the following packages:

LSP and language support:

LSP: the base LSP client
LSP-typescript: TypeScript/JS via tsserver
LSP-biome: Biome linting, formatting, and code actions
LSP-css: CSS language server
LSP-copilot: GitHub Copilot support

Developer experience:

SideBarEnhancements: adds missing file operations to the sidebar
A File Icon: file type icons
BracketHighlighter: bracket pair matching
AutoFileName: path autocomplete in import strings
Pretty JSON: to parse and format JSON files
MDX: MDX syntax definitions

We use Biome for linting and code formatting, but if your codebase uses ESLint and Prettier instead of Biome, check out this other post.

Tip: you can use the Package Control: Advanced Install Packages option to install multiple packages in one go.

Note: I don't use any Git packages in Sublime Text because I use Sublime Merge for things like visually scanning diffs more easily, resolving merge conflicts, and checking the history of a file. For most other things I use Git directly in my terminal (iTerm). If you'd like to use both Git and the terminal from within Sublime Text, look into the Terminus and GitSavvy packages.

3) TypeScript support

To get TypeScript to work you'll need to point LSP-typescript at your monorepo root's TypeScript install. Go to Settings > Package Settings > LSP-typescript > Settings and add:

// Settings in here override those in "LSP-typescript/LSP-typescript.sublime-settings"
{
    "typescript-tsdk": "/Users/fed/workspace/repository-name/node_modules/typescript/lib"
}

Note: the ~ home directory shortcut does not work in Sublime settings. You'll need to use the full absolute path.

Something handy to add is support for "jump to definition" using Option+click. For this we'll add a new mouse shortcut (Settings > Mouse Bindings) and add the following:

[
    {
        "button": "button1", // left mouse button
        "count": 1, // single click
        "modifiers": ["option"],
        "press_command": "drag_select",
        "command": "lsp_symbol_definition"
    }
]

4) LSP settings

Go to Settings > Package Settings > LSP > Settings. This is where the global LSP configuration lives. This is the full config I ended up with:

// Settings in here override those in "LSP/LSP.sublime-settings"
{
    "lsp_format_on_save": true,
    "clients": {
        "LSP-biome": {
            "enabled": true,
            "initializationOptions": {
                "requireConfiguration": true
            }
        },
        "LSP-typescript": {
            "enabled": true,
            "settings": {
                "typescript.format.enable": false,
                "javascript.format.enable": false
            }
        }
    }
}

Note: requireConfiguration: true ensures Biome only starts running where a biome.json exists. TypeScript formatting is disabled because Biome (or Prettier) handles that instead.

5) Project file

Create a <something>.sublime-project file at your repo root. Don't call it .sublime-project with a leading dot as Sublime will append .sublime-project again and produce a broken double extension filename. The name could be anything, it doesn't really matter. If you are set on not using a name, make sure you don't have a double extension.

Here's the content of my .sublime-project file:

{
    "folders": [
        {
            "path": ".",
            "folder_exclude_patterns": ["node_modules", ".turbo", "dist", ".cache"],
            "file_exclude_patterns": ["*.lock"]
        }
    ]
}

To open the codebase in Sublime Text, we'll open the project via Project > Open Project (and not File > Open). If the Open button is disabled, click the .sublime-project file itself rather than just navigating to the folder. If you can't see it because it starts with a dot, press Cmd+Shift+. to show all hidden files.

If you get an error like Unable to read project .sublime-project.sublime-project, delete the .sublime-workspace file, as it may still reference the old broken filename, and Sublime will regenerate it:

rm <something>.sublime-workspace

Alternatively, you could also open the project from your terminal (more on this later):

subl /path/to/project/.sublime-project

6) Solving the Node.js PATH problem

This step took me a while to figure out. When you open Sublime from the Dock or Finder, it won't inherit your shell's PATH. This means it can't find Node when nvm manages it, and in turn, LSP packages that depend on Node (like LSP-biome and LSP-typescript) cannot find the Node runtime.

This is the error message I was getting:

Could not start LSP-biome due to not being able to resolve suitable Node.js runtime on the PATH.

The easiest solution is to install a stable Node via Homebrew:

brew install node

This gets you a copy of Node at /opt/homebrew/bin/node, which never changes regardless of what you are doing with nvm. Your nvm Node is still active in the terminal for any actual project work, and more importantly they don't conflict.

Note: If you're disciplined about always using opening your projects using subl, you don't strictly need this setting (see below).

7) Opening a project from the terminal

Similarly, when you launch Sublime from your terminal using open -a "Sublime Text", macOS starts it as a GUI application outside of your shell environment. Again, this doesn't load .zshrc or .zprofile, so Sublime Text has no knowledge of anything you've set up there, including nvm, Homebrew's bin directory, or your custom PATH.

To properly open Sublime from the terminal you need the subl binary on your PATH. Apparently there's no UI option for this in Sublime Text 4 on Mac, so the workaround is to add the Sublime bin folder to your PATH in your ~/.zprofile:

echo 'export PATH="/Applications/Sublime Text.app/Contents/SharedSupport/bin:$PATH"' >> ~/.zprofile

Now you can open your project with:

subl /path/to/<something>.sublime-project

8) User settings

Besides your editor preferences in Settings > Settings, we'll need to add these two settings:

{
    // ... the rest of your user settings ...
    "index_files": false,
    "show_definitions": false
}

index_files: false disables Sublime's built-in code indexing, which is redundant when LSP is running and just wastes CPU.
show_definitions: false prevents Sublime's native hover popup from conflicting with LSP hovers.

This is what my entire Preferences.sublime-settings file looks like:

{
    "font_size": 20,
    "index_files": false,
    "line_padding_top": 4,
    "line_padding_bottom": 4,
    "word_wrap": true,
    "highlight_line": true,
    "block_caret": true,
    "caret_style": "smooth",
    "scroll_past_end": 0.5,
    "show_definitions": false,
    "mini_diff": true,
    "highlight_modified_tabs": true,
    "indent_guide_options": ["draw_normal", "draw_active"],
    "rulers": [100, 120]
}

9) Using Copilot via LSP-copilot

Once the LSP-copilot plugin is installed, make sure to log in with the browser.

I wrote this lsp-copilot-chat-context plugin to get the file and line(s) context automatically populated in the Copilot chat window, and also disabled the autocompletion functionality in the LSP-copilot settings:

// Settings in here override those in "LSP-copilot/LSP-copilot.sublime-settings"
{
    "settings": {
        "auto_ask_completions": false
    }
}

10) Wishlist

Something I couldn't get to work is CSS Modules class name autocompletion. It seems there's no Sublime equivalent to the VSCode CSS Modules extension. LSP-css gives us vanilla CSS completions but won't resolve styles.myClass across files.

A self study roadmap for engineers transitioning to pure maths

2026-01-06T00:00:00Z

If you did an engineering degree, you probably came out the other end thinking you knew a fair bit of maths. And I think that's fair: calculus, linear algebra, differential equations, probability... we covered all of it. The thing is, we covered it in the way engineers cover maths: here is the tool, here is how you use it, now apply it to this problem. Nobody really stopped to ask why it works, or whether it could be proved, or what assumptions we were quietly sweeping under the rug.

That sat fine with me for a long time. But at some point I started pulling on that thread and realised that knowing the mechanics is not the same as understanding the mathematics. I can tell you what a limit is. I can't prove, from first principles, that the real numbers are complete enough to support that definition in the first place. There's a whole layer of rigour underneath everything I learned that I never had/got to to engage with. So I decided to go back and do it properly, the way pure mathematicians do it: definitions, axioms, theorems, proofs, no shortcuts. This post is my roadmap for how I'm tackling that.

Prerequisites

Before starting taking any of the courses below, it'd be a good idea to read How to Prove It by Daniel Velleman. This book teaches proof writing and makes the transition from engineering thinking a bit easier.

1) Learn proof writing

Introduction to Mathematical Thinking (Coursera, Dr. Keith Devlin)

This course serves as a bridge: it teaches proof construction and mathematical logic, and focuses on the transition from a computational mindset to an analytical one. It is particularly handy for unlearning the habit of looking for a numerical answer and instead focusing on the validity of the argument.

2) Real analysis

18.100A Real Analysis (MIT OCW, Dr. Casey Rodriguez)

From what I've seen, this is a bit of a traditional entry point for engineers moving into pure maths. This course rebuilds calculus from axioms using rigorous proofs: epsilon-delta, sequences, continuity, and compactness. A plus is that, because as an engineer the intuition is already there, it's easy to focus entirely on proof technique rather than understanding any new concepts.

3) Abstract algebra

18.701 Algebra I (MIT OCW, Prof. Michael Artin)

This course covers groups, rings, and fields, which I found to be a significant step up in abstraction from analysis. This course is pure proof work throughout.

4) Linear algebra

18.06 Linear Algebra (MIT OCW, Prof. Gilbert Strang)

The approach of this course is geometric and intuitive, which makes it excellent for building understanding, but it is not really proof based. If you have an engineering degree you have almost certainly covered most of this content already, and could skip the course videos and go straight to Axler, using 18.06 only as a reference for anything that feels unfamiliar or as a refresher before starting reading Axler.

Recommended books

Spivak, Calculus: this is a rigorous calculus book used in a number of university pure maths courses. Same as with 18.100A, this book is ideal to ramp up on proof writing because the content is already familiar, so you can focus entirely on absorbing the proof style rather than trying to make sense of the new concepts.
Abbott, Understanding Analysis: covers similar ground to Spivak, but Abbott spends time motivating definitions before formalising them. A good companion for MIT 18.100A, and a bit of a gentler entry point if Spivak's density feels like too much too soon.
Dummit & Foote, Abstract Algebra: this is a good starting point for abstract algebra for someone still building proof fluency, and is a good companion for 18.701.
Axler, Linear Algebra Done Right: in engineering you learn linear algebra around determinants: calculate the determinant, find the eigenvalues, done. Axler throws that out and rebuilds the whole subject from a proof first perspective: it covers the same material but sort of forces you to actually understand why it works rather than just how to calcualte it. A good book to use alongside 18.06.

How to block distracting sites on Mac

2025-09-19T00:00:00Z

Every time we visit a website our OS checks a file called /etc/hosts before it ever reaches our DNS server. If it finds an entry for that domain, it uses the address we've got listed there instead of looking it up.

By pointing a domain to 0.0.0.0 (which is known as a "non routable address") the request goes nowhere and the site will just not load.

The first step is to edit the /etc/hosts file. The file is owned by root, so we'll need sudo:

sudo vim /etc/hosts

You can use any editor you prefer, it doesn't need to be vim.

And then add the following to the end of the file (or anywhere, really):

# Blocked sites
0.0.0.0 reddit.com
0.0.0.0 www.reddit.com
0.0.0.0 old.reddit.com
0.0.0.0 x.com
0.0.0.0 www.x.com
0.0.0.0 m.x.com
0.0.0.0 bsky.app
0.0.0.0 www.bsky.app

The idea is that you replace these with whatever your personal time sinks are. Just a heads up that unfortunately the hosts file doesn't support wildcard entries, so we are going to need both the "bare domain" and the www subdomain, since they resolve separately.

The final step is to flush the cache. The OS caches DNS lookups, so the changes may not take effect immediately and you may need to flush the cache to force it:

sudo killall -HUP mDNSResponder

If for any reason you ever need to undo this, just remove the lines you added from the /etc/hosts file and flush the cache again.

Note that this blocks the domains system wide across all browsers and apps too.

Building a mental model of the Elm Architecture (for React developers)

2025-07-22T00:00:00Z

If you, like me, are coming to Elm from Reactland, the Elm Architecture will feel familiar in some ways and weirdly strict in others. Figured I'd jot down some notes on what the main concepts are, how they compare to React, and how I think about this.

The main concepts

The Elm Architecture is a cycle with three main moving parts: a Model, a View, and an Update function. Model holds your app data. View takes that data and renders it as HTML. Update handles anything that happens and produces a new Model. That's it.

When something happens in your app, it sends a message to Update, which returns a new Model, which causes View to re-render. It's a one way loop, every time, no exceptions.

Messages

Messages are a union type called Msg, which means every possible thing that can happen in your app is declared upfront as a specific type. The compiler knows about all of them, and if your Update function doesn't handle one, it won't compile.

Let's say we are building a surf forecast app where you type in a beach name and fetch the forecast. For this app your messages might look like this:

type Msg
    = BeachInputChanged String
    | FetchForecast
    | ForecastReceived (Result Http.Error Forecast)

That Msg type can only ever be one of those three things.

Side note: A union type is a type that can be one of several predefined variants. So instead of a string that could be anything, you explicitly list every possible value upfront.

Model

The Model is just a record that holds your app state. In Elm we model every possible state explicitly rather than leaving fields that might or might not have a value. For the surf app, that means a Status union type that can only be one of four things:

type Status
    = Idle
    | Loading
    | Success Forecast
    | Failure String

There's no isLoading: true floating around with no corresponding data, and no forecast field that may or may not be null. Every possible state has a name and the compiler knows about all of them.

Update

The Update function takes the current Model and a message, and returns a new Model along with any side effects. It's a case expression over Msg, which means the compiler double checks that every variant is handled. Add a new message type and forget to update this function, and it won't compile.

Update always returns a tuple of (Model, Cmd Msg). When there's nothing async to do, you return Cmd.none. When you need a side effect, like firing an HTTP request, you return a command alongside the new Model.

View

The View function takes the Model and returns some HTML. It's a pure function, meaning the same Model always produces the same HTML. Because Status is a union type, your view has to handle all four cases (the compiler won't let you skip one).

Commands and subscriptions

Side effects (like HTTP requests) never live inside your logic. They're kicked out to/handled separately through commands (Cmd) and subscriptions (Sub).

A command is something you ask the Elm runtime to do on your behalf, like fetching data. You hand it back from Update and the runtime handles the actual request. When the response comes back, the runtime sends a message back into your Update function.

A subscription is how you listen for ongoing events like timers or websocket messages. The point is that side effects never sneak into your logic. They're always explicit, always declared, and always handled in one place.

In Elm the rule is: your functions are pure and the runtime handles everything else. This is way different from React where useEffect hooks are scattered through your components and side effects can happen pretty much anywhere.

How it compares to MVC

In some places online you can see this architecture described as Model/View/Update rather than Model/View/Controller. In traditional MVC, your controller can directly manipulate both the model and the view, which means you get two way data binding and all the unpredictability that comes with it.

Elm doesn't let you do that. Data flows down from Model to View, and messages flow up from View to Update. That's the only direction things move, and it's enforced by the architecture.

How it compares to Flux

Elm is actually very close to Flux conceptually: both use an unidirectional data flow, centralise state management, and have the concept of events triggering state changes.

The difference is that Flux has more moving parts. You've got actions, a dispatcher, multiple stores, and your React views all as separate concepts. Elm consolidates most of that into fewer concepts. Messages are like Flux actions, but your Update function combines the dispatcher and store logic into one place, and there's only ever one Model rather than multiple stores.

The other big difference is strictness. Flux runs in JavaScript, so immutability and pure functions are encouraged but never enforced. Elm is a proper functional language, so immutability isn't a convention you should try and follow, rather something baked in to the language itself. Your Update function and View function are both pure functions, and the compiler guarantees it.

As an aside, Redux kind of sits between the two. It ditched the Flux dispatcher and consolidated stores into a single one, which makes it much closer to the Elm Architecture in practice. The main thing it can't replicate is the compiler guarantees.

How it compares to React

As we said before, state in React (via useEffect calls) lives wherever you put it, and side effects (via useEffect calls) can be handled pretty much anywhere in any component.

In Elm every single change to your app state has to go through the Update function via a message. There's no useState or useEffect. Every button click, every form input, every HTTP response becomes a specific message type, and Update handles it. Side effects are kicked out to commands and subscriptions rather than living inside component lifecycle hooks, and that is the only way anything changes.

A useful mental model to help think of this is: your entire app is basically one giant reducer function. Instead of combining multiple reducers, you've got a single Update function that takes the current Model and a message, and returns a new Model. Every possible thing that can happen in your app is a predefined message type, and Update is a big pattern match that says "if I get this message, here's how the Model changes".

An example

Here's the code for the surf forecast app we've been using as an example so far. The idea is that you type in a beach name, hit the button, and get back the forecast.

The main function ties everything together and then hands it over to the Elm runtime. From there the runtime owns the loop: it calls view to render, listens for events, sends them to update as messages, gets back a new Model and any commands, executes the commands, and starts again.

module Main exposing (main)

import Browser
import Html exposing (..)
import Html.Attributes exposing (..)
import Html.Events exposing (..)
import Http
import Json.Decode exposing (Decoder, field, float, map3)


-- MODEL

type alias Forecast =
    { waveHeight : Float
    , wavePeriod : Float
    , windSpeed : Float
    }

type Status
    = Idle
    | Loading
    | Success Forecast
    | Failure String

type alias Model =
    { beach : String
    , status : Status
    }

init : Model
init =
    { beach = ""
    , status = Idle
    }


-- MESSAGES

type Msg
    = BeachInputChanged String
    | FetchForecast
    | ForecastReceived (Result Http.Error Forecast)


-- UPDATE

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        BeachInputChanged input ->
            ( { model | beach = input }, Cmd.none )

        FetchForecast ->
            ( { model | status = Loading }, fetchForecast model.beach )

        ForecastReceived (Ok forecast) ->
            ( { model | status = Success forecast }, Cmd.none )

        ForecastReceived (Err _) ->
            ( { model | status = Failure "Couldn't fetch the forecast. Try again." }, Cmd.none )


-- COMMANDS

fetchForecast : String -> Cmd Msg
fetchForecast beach =
    Http.get
        { url = "https://api.surfline.com/surf?beach=" ++ beach
        , expect = Http.expectJson ForecastReceived forecastDecoder
        }

forecastDecoder : Decoder Forecast
forecastDecoder =
    map3 Forecast
        (field "wave_height" float)
        (field "wave_period" float)
        (field "wind_speed" float)


-- VIEW

view : Model -> Html Msg
view model =
    div []
        [ input
            [ placeholder "Enter a beach name"
            , value model.beach
            , onInput BeachInputChanged
            ]
            []
        , button [ onClick FetchForecast ] [ text "Get forecast" ]
        , viewStatus model.status
        ]

viewStatus : Status -> Html Msg
viewStatus status =
    case status of
        Idle ->
            text ""

        Loading ->
            p [] [ text "Fetching forecast..." ]

        Success forecast ->
            div []
                [ p [] [ text ("Wave height: " ++ String.fromFloat forecast.waveHeight ++ "m") ]
                , p [] [ text ("Wave period: " ++ String.fromFloat forecast.wavePeriod ++ "s") ]
                , p [] [ text ("Wind speed: " ++ String.fromFloat forecast.windSpeed ++ " km/h") ]
                ]

        Failure message ->
            p [] [ text message ]


-- MAIN

main : Program () Model Msg
main =
    Browser.element
        { init = \_ -> ( init, Cmd.none )
        , update = update
        , view = view
        , subscriptions = \_ -> Sub.none
        }

App defaults

2025-07-19T00:00:00Z

This "defaults" list is inspired by Robb Knight's collection of app defaults posts, where a huge number of bloggers share their default apps and services. I like how these lists make it easy to find and explore other personal blogs and setups, similarly to what happens with "now" or "uses" pages.

These unassuming and reliable everyday tools are deeply integrated into my habits/routine, and handle life's background tasks allowing me to focus on what actually matters. My approach is to stick with default apps until they can't do what I need, only switching when the built-in option genuinely can't handle my use case.

Mail Client: Gmail web client on my laptop, Mail.app on my phone
Mail Server: Gmail, iCloud with custom domain
Notes: Apple Notes
To-Do: Reminders
iPhone Photo Shooting: Camera.app
Photo Management: Apple Photos
Calendar: Google Calendar via Calendar.app on both my laptop and phone
Cloud File Storage: iCloud Drive, Google Drive
RSS: NetNewsWire
Contacts: Apple Contacts
Browser: Safari
Chat: Messages, WhatsApp
Bookmarks: Browser's built-in tool
Read It Later: Instapaper
Word Processing: iA Writer, Google Docs
Spreadsheets: Google Sheets
Presentations: Remark, Google Slides
Shopping Lists: pen and paper, Reminders
Meal Planning: n/a
Budgeting and Personal Finance: custom spreadsheet
News: ABC News, The Guardian
Music: Apple Music
Podcasts: Apple Podcasts
Password Management: Bitwarden

Here's some extra categories I also wanted to include:

Weather: BOM, Apple Weather
Reading: Physical copies from local library, Kindle
Book tracking: Goodreads
Code editor: Visual Studio Code, Sublime Text
Git GUI client: Sublime Merge
Terminal: iTerm2
Launcher: Raycast
Clipboard manager: Raycast
Screenshots: Mac's built-in tool
Social: Mastodon, BlueSky, Reddit
Search engine: DuckDuckGo

Edit October 2025: replaced Spotify with Apple Music, and stopped using Signal, Xnip and Simplenote. Still using the DuckDuckGo browser on my laptop but had to go back to Safari on my phone as some core functionality is still unsupported, e.g. adding events to my calendar from the browser or persistent website blocking via Freedom.

Trading complexity for simplicity with 11ty

2025-07-09T00:00:00Z

After years of dealing with an unnecessarily complex codebase for my blog, this week I made the switch from Gatsby to 11ty.

Gatsby is an impressive framework, but for a simple blog like this it feels like a bit of an overkill. We've got React components for static content with no interactivity, GraphQL queries to fetch markdown files from my own filesystem, CSS-in-JS solutions for styling what is honestly quite a simple UI, and dozens of plugins each adding their own dependencies and potential breaking points, which is particularly painful when upgrading dependencies.

I really needed a bicycle to get around town, but Gatsby gave me an F1 race car. Sure, it's powerful and feature-rich, but it comes with a lot of overhead for what should be a simple journey.

In an effort to make this codebase a bit simpler, I decided to give 11ty a hot go, and right away I realised it was exactly what I was after.

This is what my workflow looks like now:

A few simple, readable template files (using Nunjucks which works out of the box) handle the layout
Good old CSS files that work exactly as you'd expect, especially now that CSS got better in the past few years
Some vanilla JS code only when actually needed for interactivity
Markdown files that become HTML pages

The migration itself was surprisingly smooth. Heaps of features work out of the box, and the rest were super simply to set up via plugins without much configuration (if any!).

And one of the best parts is that the build process is now really quick, especially when working locally.

This goes to show that sometimes the best solution isn't the most powerful one but the one that's most appropriate for our particular use case. Of course your mileage may vary: for example if you are building a site with complex client-side interactions or a web app with dynamic content, then Gatsby or a similar tool may be the best choice. But at least for this blog 11ty's simplicity beats Gatsby's power every time.

I'm still learning everything 11ty has to offer, and I'm sure it can handle complex use cases like Gatsby, but so far it feels really optimised for simplicity, and I'm loving the dev experience.

If you are curious about the differences and the before/after comparison, you can check the old and new codebases here:

Choosing between links and buttons

2024-03-05T00:00:00Z

This write-up is a collection of rules of thumb to help you decide whether your interactive control should be a link or a button, and the accessibility implications of choosing one over the other. We'll explore five different categories: semantics, state, tab order, interactions, and using Voiceover's rotor or similar.

Semantics

Both links and buttons are interactive elements and allow users to perform an action. However, links are very specific in how they get used, while buttons are more general as they "imply" less and give the user less options.

Let's start with links. Links take you to a new location, which could be a new page, a section of the current page or even a file to download (e.g. a PDF file). This location is defined via the href attribute, which should not be blank or have a value of #.

A link should have the following behaviours:

it should be activated with the Enter key
it should semantically "go" somewhere (rather than "do" something)
it should allow the user to open the destination in either a new tab or a new window
it should never trigger an action such us submitting a form or deleting something from the page

If some of these don't make sense, then your control probably shouldn't be a link.

Similarly, if you are disabling the ability to open a link in a new tab or window, then it's also most likely not a link.

In particular, opening/closing a modal is rarely suitable for a link, unless the modal dialog has its own URL and gets automatically rendered whenever the user visits that URL.

Buttons, on the other hand, perform an action without affecting the user's current location. Users would not expect their location in the application to change after pressing a button.

Examples of actions performed by buttons could be submitting a form, opening a modal (as long as the URL does not change), opening a popup, revealing or hiding content (e.g. an accordion), playing or pausing audio or video, triggering an action in the backend (e.g. deleting an element), etc.

As mentioned before, buttons are more general and there are less expectations on what they do: clicking on a button could do anything, it's typically more vague and less specific than a link.

Buttons come in different flavours:

type="button": this is a generic button that does not trigger a form submission by default, and requires us to use JavaScript to define its behaviour.
type="submit": this comes with some additional built-in information, as a submit button always causes a change in context, like going to a new page, or replacing the contents of the page. Using this particular button type provides some extra information that can help users understand what's about to happen.
type="reset": this is a special button that clears/resets all form fields to their default values. There should be no change in context/location after using a reset button.

For both links and buttons, semantics is really important because it directly affects user expectations: if a screen reader announces an element as a "link" or "button", users have expectations about what will happen when they activate that control. If something else happens, this can be disorienting or jarring to some users.

For links, some of these expectations/affordances include supporting functionality such as opening the target location in the current tab (by default, if you don't do anything) or a new tab/window (including a private one) if you choose to do so, allowing you to "Save as" which is particularly useful for some filetypes including PDF or images, as well as allowing a page refresh without losing my current location.

State

Another difference between these two controls is the states they can be in.

Links have the following states:

:link (this is an element that has not yet been visited)
:visited
:focus
:hover
:active

Sighted users can sometimes recognise visited links from the text colour used (by default this is typically implemented as a purple link instead of a blue one), while screen reader users get this piece of information announced when they navigate to the link. If you are suppressing any of these states, then you should consider whether your control is in fact a link.

Buttons, on the other hand, don't have the concept of whether they have already been pressed (and I'm referring to the same :visited state links have, and not aria-pressed for toggles). We can however style different states: :focus, :hover and :active.

Buttons can also be either enabled or disabled. Disabled buttons warrant a whole blog post of their own. For now, if you are going to disable a button make sure to provide enough information on how to get to be enabled again. And if possible look at a different user experience such as inline validation for forms instead of relying on disabled buttons.

Tab order

Both buttons and links are interactive elements and as such are, by default, in the tab order, with some exceptions:

Links will not be in the tab order if they don't have an href attribute, or if the href attribute is empty.
Buttons will not be in the tab order if they are disabled.

Be careful when adding tabindex="-1" to an element as this will remove it from the tab order. This means that even though you would still be able to focus on it programatically using JavaScript, users would not be able to tab onto it.

And while we are at it, never remove the outline of any of these interactive elements on focus. Keyboard-only sighted users rely on this outline (or any other similar visual cue) to keep track of what the active element currently is.

Interactions

There's also a subtle but major difference in how users would go about activating these two controls:

Buttons can be activated by both the Enter and Space keys.
Links, however, can only be activated by pressing the Enter key. If you press the Space key while focusing on a link, the browser will scroll down the page, as this is the default behaviour of the Space key.

This is why affordances are important. People perceive cues that tell them what to do with an object. For example, a door handle invites you to grasp and pull down, but a door knob requires you to grasp and turn, engaging a different motion to open the door. Going back to our links and buttons, and focusing on sighted users, if an interactive control looks like a button, you wouldn't expect a "page down" event to be triggered if you are trying to activate the control using the Space key. Same for screen reader users, you want to be able to activate a button with the Space key if it gets announced as a button.

Rotor and Quick Keys

In VoiceOver's rotor, links will appear in the "Links" section, while buttons would be listed in both the "Form controls" and "Buttons" sections. The same applies to similar tools, e.g. Navigation Quick Keys in JAWS.

Discoverability is important, and we need to consider all our users. If your interactive control is not coded properly then it will show up in the wrong place (or not show up at all!).

Building your own accessible button

Now that we understand how a button is supposed to behave, let's look at how we could implement one from scratch in a way that the end result is accessible.

Let's make it very clear though that this is not recommended and ideally you'd use a semantic button instead. But if you absolutely cannot do that because of restrictions outside of your control, then you'll need to make sure you support a number of behaviours:

Add role="button" so that your element has the right semantics
Add tabIndex={0} to add your element to the tab order
Add an onClick event handler so that you can click or tap on your element
Add an onKeyDown event handler so that you can activate your control using both the Enter and Space keys
Add custom styles to make sure we at least have a focus ring or similar for the focus state.

This is what a simplified end result would look like:

function CustomButton() {
	const handleClick = () => {
		// ... your logic here
	};

	const handleKeyDown = (event) => {
		if (event.key === "Enter" || event.key === " ") {
			event.preventDefault(); // Prevent scrolling on Space press
			handleClick();
		}
	};

	return (
		<span role="button" tabIndex={0} onClick={handleClick} onKeyDown={handleKeyDown} className="custom-button">
			Click me
		</span>
	);
}

Also note that even though I used React for the code example above, this is not React-specific and applies regardless of the library/framework you are using.

Configuring Sublime Text to work with Prettier and ESLint

2022-03-12T00:00:00Z

I've been a Sublime Text user for the longest time. Even though I didn't switch to Visual Studio Code right away when it got mainstream, I did change in the end. However I'm still a massive Sublime Text fan to this day and still use it daily for a bunch of different things.

Here are some instructions, just for fun, on how to configure Sublime Text to automatically fix errors and format files on save using ESLint and Prettier.

Enable the `subl` command line tool

First things first, we've got to make sure the subl command line tool is available and working by adding the Sublime Text bin folder to our PATH in ~/.zprofile (as per the official docs):

echo 'export PATH="/Applications/Sublime Text.app/Contents/SharedSupport/bin:$PATH"' >> ~/.zprofile

This will let us open Sublime Text from the terminal so it inherits our shell's PATH, and is particularly important for all the Node dependent packages below.

Install JsPrettier

For this package to work we'll need to make sure prettier is installed locally in our project:

# npm
npm install --save-dev prettier

# yarn
yarn add --dev prettier

In our JsPrettier.sublime-settings config file we'll point node_path at a stable Node install that won't change when we update Node (e.g. via nvm). A Homebrew-managed Node install works well for this and no, nvm's Node and Homebrew's Node won't clash. In your terminal, nvm controls which Node is active via your shell PATH, so your project work is unaffected. LSP on the other hand would only use the Homebrew Node because you've explicitly pointed node_path at it.

{
	"auto_format_on_save": true,
	"node_path": "/opt/homebrew/bin/node",
	"prettier_cli_path": "/absolute/path/to/project/node_modules/prettier/bin-prettier.js"
}

Two things here:

Sublime does not expand ~ in settings values, so paths like ~/.nvm/... will not work. Always use full absolute paths.
You may get away without setting prettier_cli_path explicitly, but this is particularly important if you are working in a monorepo, as leaving it empty causes JsPrettier to find the nearest node_modules/.bin/prettier, which may be a nested package rather than the root.

Install SublimeLinter and SublimeLinter-eslint

We need to make sure eslint is installed locally in our project:

# npm
npm install --save-dev eslint

# yarn
yarn add --dev eslint

In our SublimeLinter.sublime-settings config file, we'll point PATH at the directory containing the Node binary. Again, it's important that we use a full absolute path, as ~ is not expanded by Sublime:

{
	"linters": {
		"eslint": {
			"env": {
				"PATH": "/opt/homebrew/bin"
			},
			"args": ["--env=es6"]
		}
	}
}

Install ESLint-Formatter

We'll need to install this package if we want to automatically fix any errors on file save. Once again we'll have to edit the config file for this package, in this case ESLint-Formatter.sublime-settings, and point it to the right location of our Node install:

{
	"node_path": {
		"osx": "/opt/homebrew/bin/node"
	},
	"format_on_save": true,
	"format_on_save_extensions": ["js", "jsx", "ts", "tsx"]
}

Web frontend devtools

2021-11-28T00:00:00Z

A collection of frontend web development tools and resources.

General

createapp.dev: A project scaffolding configurator for Webpack/Parcel. You can select the features you need (React, TS, Babel, ESLint, etc.) and it will generate a starter config or project structure without manual setup.
astexplorer.net: You can paste JavaScript (or other languages) and inspect the resulting Abstract Syntax Tree in real time. Useful when writing Babel plugins, ESLint rules, or codemods.
httpstatuses.com: A quick reference for HTTP status codes with easy to understand explanations of what each code means and when it applies.
keycode.info: You can press any key and see the corresponding keyCode, key, code, and which values. Comes in handy when working with keyboard event handlers.
bundlephobia.com: You can look up the minified and gzipped size of any npm package and see how it will affect your install time. It also surfaces lighter alternatives if they exist.
bundle-buddy.com: You can analyse Webpack/Parcel bundle stats to identify duplicated code across chunks and decide what to split or deduplicate.
diffchecker.com: You can compare two blocks of text, code, images, or PDFs side by side and see the differences highlighted.
jsonformatter.curiousconcept.com: You can format, validate, and prettify raw JSON to make an unreadable blob easier to read.
icomoon.io: An icon library generator, you can pick multiple icons and export a custom icon font or SVG sprite.
browserhacks.com: A catalogue of browser specific CSS/JS hacks for targeting rules at particular browsers without relying on feature detection.
loremipsum.io: To generate placeholder text for use in prototypes.
tiny.photos: An image optimisation service.

Web APIs and browser compatibility

caniuse.com: The standard reference for checking browser support across CSS features, JavaScript APIs, and HTML elements, broken down by browser and version.
node.green: You can check ECMAScript feature support across Node.js versions, covering the same ground as caniuse but specifically for the server side Node runtime.

CSS

specificity.keegan.st: A specificity calculator for CSS selectors. You can paste a selector and get its score broken down by component (IDs, classes, and elements).
brumm.af/shadows: An interactive box-shadow editor that lets you layer and adjust multiple shadows and copy the resulting CSS.
csstriggers.com: Look up which CSS properties trigger layout, paint, or composite operations in the browser rendering pipeline (useful for writing more performant animations/transitions).
webfx.com hex to RGB: Convert colours across notations/formats.

Regex

regexr.com: A regex editor with match highlighting. It also offers a syntax reference which comes in handy.
regexly.js.org: A regex tester with a visual breakdown of matches.
regexper.com: You can convert a regex pattern into a railroad diagram, making the logic of complex expressions easier to follow visually.
regex101.com: A regex tester supporting multiple flavours (PCRE, JavaScript, Python, etc.). It has a built in debugger.
ihateregex.io: A library of common patterns (emails, URLs, phone numbers, etc.) with visual diagrams.
regexpal.com: Another JavaScript regex tester with live match highlighting.

Accessibility

Here are some links to a handful of tools you might find useful when working on and testing web accessibility.

Screen readers

VoiceOver (already shipped with MacOS): pair with Safari
NVDA: pair with Firefox on Windows
JAWS: pair with Chrome on Windows
ChromeVox (built-in on Chromebooks): pair with Chrome

Screen reader plugins

If you are working with NVDA, the Focus Highlight Plugin might come in handy as it provides a way to get a visual indication of the focused item when NVDA is on.

VSCode extensions

axe Accessibility Linter

Chrome extensions

Bookmarklets

ANDI (Accessible Name & Description Inspector)

Apps

Colour Contrast Analyser

Useful webapps/websites

Browser-based devtools

chrome://accessibility/ (Chrome)
edge://accessibility/ (Edge)
Accessibility Inspector (Firefox)
Accessibility Node Inspection in WebKit Web Inspector (Safari)

Jira search engine in your browser

2020-04-21T00:00:00Z

Here's how you can add the ability to search and directly access Jira tickets from within your browser's URL bar.

Go to Settings > Search Engines > Manage Search Engines and add a new engine with the details below:

Save the changes and in your omnibox, type in jira and press tab, then enter a ticket name and after hitting enter you should be redirected there.

Also, since we are using Jira's search URL, we can search for tickets via keywords if you don't remember the ticket number.

Code reviewing checklist

2020-03-12T00:00:00Z

Here's a brief and high level description of the things that I usually try to look out for when reviewing someone else's frontend code. Just a disclaimer that by no means this is supposed to be an exhaustive checklist, rather a compendium of aspects I consider worth focusing on while checking someone else's pull request.

Coding style, conventions and standards

Different people have different coding styles, and that's why I think we should try to avoid making opinionated comments on code formatting. I'd much rather have tools like ESLint or Prettier take care of that instead of seeing people act as human linters. Reviewers can make more insightful contributions than pointing out we need an extra line break after a variable declaration.

Sometimes, however, there are conventions that as a team we've come to adopt but which might not be easily enforced using a linter. For instance we might agree upon appending $ to all our event streams names, or naming our event handlers in a certain way (e.g. onClick vs. handleClick), etc. The might be value in pointing out things like these during code reviews for the sake of consistency.

Complexity, readability and maintainability

I think it's important to write code that is both easy to understand and to reason about. With this in mind, we might want to focus our efforts on anything that could potentially help us or other developers understand our changes at a later point in time, such as ensuring the solution is no more complex than it needs to be, making variable names as descriptive as possible, requesting comments on the "why" (as opposed to the "what") where the purpose of some logic is a bit obscure or at least not too obvious, suggesting to move complex boolean conditionals into their own variables, extracting complex logic into its own function or adding any supporting documentation, among many others.

Architectural overview

It usually pays off to look at the code diff at a higher level to understand if the solution being implemented is solid and makes sense, and it's not just a temporary workaround that'll come back to bite us in the future.

We need to bear in mind, however, that sometimes tight deadlines happen and making compromises is inevitable. In situations like these it's important to create follow up tasks to tackle tech debt sooner rather than later, while both the context and knowledge of the current implementation are still fresh in our heads.

Also, we could consider looking for similar solutions that might have already been implemented somewhere else in the codebase. Sometimes we can reuse existing code but the person who created the PR might have no clue such code already exists. Conversely, it's also a good idea to keep an eye out for potential abstractions that could be useful somewhere else.

Something else would be to make sure the new code doesn't break/impact anything else. Sometimes this is only possible if we know the codebase these changes are being implemented into well enough.

Automated testing

Shipping tests along with your code changes is great, but not enough. Tests should give us the confidence to build on top of or make changes to existing features in the code we are writing, and it's very important to make sure we are testing the right thing. Are we testing implementation details rather than important business logic? Are we investing resources in testing the library or framework we are using instead of the functionality that we built on top of that tool?

Also, different levels of testing should be used to test different aspects of our new code in order to cover different scenarios. Do we have an appropriate combination of unit, integration, contract and end to end tests?

Accessibility

Any new additions to the codebase need to be accessible, that's the right thing to do. We should make sure any new code can be used by screen reader and keyboard users, makes sense semantically, has an appropriate level of colour contrast, etc. There are dedicated automated testing tools, linters, browser extensions and thorough checklists that can help us make sure our changes are accessible.

Ideally we should always also conduct at least a basic level of manual testing as not all accessibility issues can be automatically detected by the tools mentioned above.

Internationalisation

Is all new content localised? This includes not only regular text content but also number formatting as well as date and time formatting.

Security

Mostly make sure we are not trusting any user input to prevent possible attacks. Are we sanitising any form of user input such as query params and input fields? Are we favouring Node.textContent over Element.innerHTML if possible? Same with React's dangerouslySetInnerHTML.

Double check we are not storing sensitive information in localStorage, sessionStorage, cookies and React/Redux state as anyone would be able to see this information on the client using DevTools.

Be careful when including any third-party scripts or dependencies as we usually have no control over what they do.

Also ensure data gets checked and validated on both the frontend and the backend -- particularly things like user permissions which could otherwise be tampered with on the client.

Performance

Make sure we are caching all data that makes sense to be cached. By caching frequently accessed data, we can significantly improve the perceived performance of our user interfaces, which results in a better user experience as pages will load faster and be more responsive.

In terms of number of bytes being shipped to the client, make sure any new assets are optimised, and any new dependencies being introduced are really necessary.

Instead of suggesting micro optimisations when performance is not yet a problem, it would be a good idea to look out for things such as expensive operations that could potentially be offloaded to a web worker to avoid blocking the UI thread, or sets of nested loops that will be eventually iterating over fairly big-sized collections.

Cross browser/platform compatibility

We should keep an eye on methods that might require polyfilling or features that need to be transpiled by Babel. For example, often times we tend to use things such as Object.entries or Array.from without checking for their browser support, to then find the application crashing on Internet Explorer or even on older versions of greenfield browsers. Same goes for using things such as the object spread operator which requires a special Babel plugin.

Things like mouse/touch/pointer events need to be handled appropriately to make sure the change works on mobile devices as well as computers. And in general, if the change makes use of any browser API, we should double check its current support.

Operational maturity and production readiness

Operational aspects revolve around delivering high quality code that is reliable, resilient and performant in a way that can be measured and tracked. Does the code include client-side error monitoring and logging so that we can get alerts when something goes wrong? Are we logging the right analytics events and performance metrics? Do we have proper error handling? Are we communicating loading states in a way that makes sense to the user? Is any new code behind a feature flag? Are we introducing any new feature flags in a way that makes it easy to clean them up later on?

Functional review

Finally, something else we can do is to check out and build the branch we are reviewing and manually test the changes. The person looking at the code diff has more context on where the complexity might be, and will therefore be more likely to identify what could possibly go wrong and also pinpoint edge cases or issues with the current changeset.

Focusing and skipping tests

2020-01-23T00:00:00Z

When writing unit tests, you might need to temporarily choose which tests to execute. You could achieve this by commenting out the tests you don't want to run, although there's also another way built in in your testing framework.

Mocha

With Mocha, you can use it.only() and describe.only() for exclusive tests. This will run just the tests marked with only and ignore the rest.

// Both tests in this describe block will run
describe.only("when something happens", () => {
	it("should do something", () => {});
	it("should do something else", () => {});
});

// This test case won't be executed
it("should also do this", () => {});

Conversely, use it.skip() and describe.skip for inclusive tests. All tests marked with skip will not be run.

// Neither of the tests in this describe block will run
describe.skip("when something happens", () => {
	it("should do something", () => {});
	it("should do something else", () => {});
});

// This test case  isn't affected by the describe.skip and will therefore be executed
it("should also do this", () => {});

You can also combine these two together. In the example below, the only test cases being run are "should do something" and "should also do this":

describe.only("when something happens", () => {
	it("should do something", () => {});
	it.skip("should do something else", () => {});
});

// This test case  isn't affected by the describe.skip and will therefore be executed
it.only("should also do this", () => {});

Jasmine

If you are using Jasmine, you can choose to run a particular test case or suite (or set of test cases/suites) by changing it() to fit() and describe() to fdescribe(), respectively.

// Both tests in this suite will run
fdescribe("when something happens", () => {
	it("should do something", () => {});
	it("should do something else", () => {});
});

// This test case won't be executed
it("should also do this", () => {});

To skip tests on the other hand, replace it() with xit() for individual test cases and describe() with xdescribe() for test suites.

// Neither of the tests in this suite will run
xdescribe("when something happens", () => {
	it("should do something", () => {});
	it("should do something else", () => {});
});

// This test case  isn't affected by the xdescribe and will therefore be run
it("should also do this", () => {});

Fixing keyboard navigation for MacOS browsers

2019-10-19T00:00:00Z

If you've ever used your keyboard to navigate a page in MacOS, you might have noticed you cannot tab through all tabbable elements on the page. Some are fine, such as buttons and input fields, but others (e.g. links) are not reachable using your keyboard.

The worst part is that this is not obvious, and there's no way for developers to enforce this setting on their sites.

Fixing Firefox

By default, there's a global system setting to modify this behaviour that you can toggle by going to System Preferences > Keyboard > Shortcuts and then clicking on the All Controls radio button, which is at the bottom of the screen in the Full Keyboard Access section.

Doing this should automatically fix Firefox, which is true to the system settings.

Firefox does not have a separate option for tab key navigation to links and form controls. In Firefox the OS X system preference takes precedence.

Update: The UI has changed a little bit in the last couple versions of MacOS. For MacOS Ventura, the option we need to enable is under System Preferences > Keyboard and is now a toggle element called "Keyboard navigation".

Fixing Safari

Safari, on the other hand, has its own setting. By default pressing the Tab key would allow you to highlight all focusable elements on the page except for links.

To change this behaviour, go to Safari > Preferences, click on the Advanced tab and finally click on the Press Tab to highlight each item on a webpage checkbox. By toggling this flag, we can now focus on all elements on the page, including links.

Note that this works for both Safari and Safari Technology Preview and needs to be done separately on both versions of the browser.

Chrome should work fine out of the box

Chrome also has a setting for this under chrome://settings/appearance. This setting is enabled by default, though. So there's no need to configure anything to make Chrome work.

Testing asynchronous code

2019-01-09T00:00:00Z

To understand what the deal is with asynchronous testing, we first need to look into what happens when we don't have any assertions in our tests.

In Mocha (and most JavaScript testing frameworks for that matter), specs with no assertions (i.e. test cases with no expect) just pass. Consider the following example:

describe("A test without assertions", () => {
	it("still passes", () => {
		const message = "rawr";
	});
});

Run this and you'll find everything is fine: the test passes and Mocha moves on without warning us no assertion has been run.

Now consider the following example:

describe("Our first async test", () => {
	it("is a false positive", () => {
		setTimeout(() => {
			expect(true).to.equal(false);
		}, 200);
	});
});

This test will pass flawlessly, while we'd expect it to fail: we've got a false positive in our test suite. This test provides no indication whatsoever there's something wrong with our code or test case.

This is because:

The assertion (the call to expect) is delayed until the next tick.
The rest of the code finishes executing and Mocha finds no assertions, making the test pass (as we've seen before).

Since the assertion is delayed until the next tick we are gonna get the next test case to fail, even though the code is fine and the test should normally pass! Just imagine how hard it is to debug cases like this.

Mocha, Jasmine and Jest automatically pass in a done callback we can use to mark our test as asynchronous: when this function is present, our test framework knows it has to wait for this callback to be called before completing the test.

describe("Our second async test", () => {
	it("works a charm as it calls done()", (done) => {
		setTimeout(() => {
			expect(true).to.equal(true);
			done();
		}, 200);
	});
});

If our code uses promises, we can skip calling done altogether and just return the promise instead — the testing framework will typically wait for the promise to resolve. If the promise gets rejected, the test will fail. This is useful if the APIs we are testing return promises instead of taking in callbacks. Here's an example:

it("returns a promise", () => {
	return fetch("https://files.fedknu.com/blog/async-testing/capitals.json")
		.then((response) => response.json())
		.then((data) => {
			expect(data.capitals[5]).to.equal("Wellington");
		});
});

Alternatively, we can use async/await in our tests to get, which at least in my opinion is the most readable version of our async tests: here there's no need to return anything nor call done at all.

it("promise with async await, no done", async () => {
	const response = await fetch("https://files.fedknu.com/blog/async-testing/capitals.json");
	const data = await response.json();

	expect(data.capitals[5]).to.equal("Wellington");
});

If you want to try this live, here's a CodeSandbox with all the code examples above.

DOM traversal and manipulation

2018-05-08T00:00:00Z

This blog contains a summary of the main and most common methods to do DOM traversal and manipulation with Vanilla JS.

DOM ready and window load

The document object emits a DOMContentLoaded event when the document is loaded and the DOM tree is constructed:

// $(document).ready(callback);
document.addEventListener("DOMContentLoaded", callback);

This window object fires a load event when iframes, images, stylesheets and scripts have been downloaded:

// $(window).load(callback);
window.addEventListener("load", callback);
window.onload = callback;

Selectors and collections

Selectors are methods of the DOM interface.

// const divs = $('ul.nav > li');
const items = document.querySelectorAll("ul.nav > li");
const firstItem = document.querySelector("ul.nav > li");

// const title = $('#title');
const title = document.getElementById("title");

// const images = $('.image');
const images = document.getElementsByClassName("image");

// const articles = $('article');
const articles = document.getElementsByTagName("article");

jQuery queries return static collections (that is, snapshots of the DOM).

Selector	Returns a collection	Returns a LIVE collection	Return type	Built-in forEach	Works with any root element
`getElementById`	🚫	N/A	Reference to an `Element` object or `null`	N/A	🚫
`getElementsByClassName`	✅	✅	`HTMLCollection`	🚫	✅
`getElementsByTagName`	✅	✅	`HTMLCollection` according to the spec (`NodeList` in WebKit) (*)	🚫	✅
`querySelector`	🚫	N/A	`Element` object or `null`	N/A	✅
`querySelectorAll`	✅	🚫	Static `NodeList` of `Element` objects	✅	✅

(*) The latest W3C specification says it returns an HTMLCollection; however, this method returns a NodeList in WebKit browsers. See bug 14869 for details.

Since all of the selectors (except getElementById) support querying any node (and not just document), finding nested elements results trivial:

// $(el).find(selector);
el.querySelectorAll(selector);

jQuery-like selector

You can recreate a very basic version of jQuery's $ selector by doing the following:

function $(selector) {
	return Array.prototype.slice.call(document.querySelectorAll(selector));
}

const button = $("#button");

Creating elements

To create a new element just pass in the tag name (a string) as an argument to the createElement method:

// $('<div />');
const newDiv = document.createElement("div");

You can create a text node by invoking the createTextNode method of the document object:

// There is no equivalent in jQuery for createTextNode.
// You can always use the DOM method, or write a jQuery wrapper around it.
// The closest thing you may be able to find is when creating new elements,
// you can specify the text part separately.
// $('<div>', { text: 'hello world' });
const newTextNode = document.createTextNode("hello world");

Adding elements to the DOM

// $(parent).append(el);
parent.appendChild(el);

// $(parent).prepend(el);
parent.prepend(el);
// ⚠️ Heads up: needs to be polyfilled on IE and Edge.

// $(parent).prepend(el);
parent.insertBefore(el, parent.firstChild);
el.insertBefore(node);

// $(el).before(htmlString);
el.insertAdjacentHTML("beforebegin", htmlString);

// $(el).after(htmlString);
el.insertAdjacentHTML("afterend", htmlString);

Traversing the DOM

// $(el).children();
el.children; // only HTMLElements
el.childNodes; // includes comments and text nodes
// ⚠️ Heads up: you can't `forEach` through `children` unless you turn it into an array first.

// $(el).parent();
el.parentNode;

// $(el).closest(selector);
el.closest(selector);

// $(el).first();
el.firstElementChild; // only HTMLElements
el.firstChild; // includes comments and text nodes

// $(el).last();
el.lastElementChild; // only HTMLElements
el.lastChild; // includes comments and text nodes

// First and last alternative
var nodeList = document.querySelectorAll(".some-class");
var first = nodeList[0];
var last = nodeList[nodeList.length - 1];

// $(el).siblings();
[].filter.call(el.parentNode.children, function (child) {
	return child !== el;
});

// $(el).prev();
el.previousElementSibling; // only HTMLElements
el.previousSibling; // includes comments and text nodes

// $(el).next();
el.nextElementSibling; // only HTMLElements
node.nextSibling; // includes comments and text nodes

// $.contains(el, child);
el !== child && el.contains(child);

Traversing a node list

var nodes = document.querySelectorAll(".class-name");

// 1.
var elements = Array.prototype.slice.call(nodes);
elements.forEach(noop);

// 2. (clean, but creates a new array)
[].forEach.call(nodes, noop);

// 3.
Array.prototype.forEach.call(nodes, noop);

Closest

Find the closest element that matches the target selector:

// $("li.item").closest("ul")
var node = document.getElementById("my-id");
var isFound = false;

while (node instanceof Element) {
	if (node.matches(".target-class")) {
		isFound = true;
		break;
	}
	node = node.parentNode;
}

You could choose to polyfill the Element.prototype.closest method:

if (Element && !Element.prototype.closest) {
	Element.prototype.closest = function (selector) {
		var el = this;
		while (el instanceof Element) {
			if (el.matches(selector)) {
				return el;
			}
			el = el.parentNode;
		}
	};
}

Removing nodes

// $(el).remove();
el.parentNode.removeChild(el);

There's also Element.remove() although it needs to be polyfilled on IE:

// $(el).remove();
el.remove();

For example, you could use the following code to remove all GIF images from the page:

[].forEach.call(document.querySelectorAll("img"), function (img) {
	if (/\.gif/i.test(img.src)) {
		img.remove();
	}
});

Replacing nodes

// $(el).replaceWith($('.first'));
el.parentNode.replaceChild(newNode, el);

// $(el).replaceWith(string);
el.outerHTML = string;

Cloning nodes

// $(el).clone();
const clone = el.cloneNode();

Make sure to pass in true to also clone children nodes:

el.cloneNode(true);

Checking if a node is empty

// $(el).is(':empty')
!el.hasChildNodes();

Emptying an element

// $(el).empty();
const el = document.getElementById("el");

while (el.firstChild) {
	el.removeChild(el.firstChild);
}

Alternatively, you could also do the following (albeit not recommended as it doesn't remove event listeners, which could lead to memory leaks in your code):

el.innerHTML = "";

Checking whether two elements are the same

// $(el).is($(otherEl));
el === otherEl;

Checking whether an element matches a selector

// $(el).is('.my-class');
el.matches(".my-class");

// $(el).is('a');
el.matches("a");

Note that matches needs to be polyfilled in older browsers. Also, many browsers implement Element.matches with a vendor prefix, under the non-standard name matchesSelector. We can play safe by using something along the lines of:

function matches(el, selector) {
	return (
		el.matches ||
		el.matchesSelector ||
		el.msMatchesSelector ||
		el.mozMatchesSelector ||
		el.webkitMatchesSelector ||
		el.oMatchesSelector
	).call(el, selector);
}

matches(el, ".my-class");

Getting and setting text content

// $(el).text();
el.textContent;

// $(el).text(string);
el.textContent = string;

There's also innerText and outerText:

innerText was non-standard, while textContent was standardised earlier.
innerText returns the visible text contained in a node, while textContent returns the full text. For example, on the following element: <span>Hello <span style="display: none;">World</span></span>, innerText will return 'Hello', while textContent will return 'Hello World'. As a result, innerText is much more performance-heavy: it requires layout information to return the result.

Here is the official warning for innerText: This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

Getting and setting outer/inner HTML

// $('<div>').append($(el).clone()).html();
el.outerHTML;

// $(el).replaceWith(string);
el.outerHTML = string;

// $(el).html();
el.innerHTML;

// $(el).html(string);
el.innerHTML = string;

// $(el).empty();
el.innerHTML = "";

Getting and setting attributes

// $(el).attr('tabindex');
el.getAttribute("tabindex");

// $(el).attr('tabindex', 3);
el.setAttribute("tabindex", 3);

Since elements are just objects, most of the times we can directly access (and set) their properties:

// Getting the element's Id
const oldId = el.id;

// Setting the element's Id
el.id = "foo";

Some other properties we can access directly are:

node.href;
node.checked;
node.disabled;
node.selected;

For data attributes we can either use el.getAttribute('data-something') or the built-in dataset object:

// $(el).data('camelCaseValue');
string = element.dataset.camelCaseValue;

// $(el).data('camelCaseValue', 'foo');
element.dataset.camelCaseValue = "foo";

Styling an element

// $(el).css('background-color', '#3cca5e');
el.style.backgroundColor = "#3cca5e";

// $(el).hide();
el.style.display = "none";

// $(el).show();
el.style.display = "";

Getting computed styles

To get the values of all CSS properties for an element you should use window.getComputedStyle(element) instead:

// $(el).css(ruleName);
getComputedStyle(el)[ruleName];

Working with CSS classes

// $(el).addClass('foo');
el.classList.add("foo");

// $(el).removeClass('foo');
el.classList.remove("foo");

// $(el).toggleClass('foo');
el.classList.toggle("foo");

// $(el).hasClass('foo');
el.classList.contains("foo");

Getting the position of an element

// $(el).outerHeight();
el.offsetHeight

// $(el).outerWidth();
el.offsetWidth

// $(el).position();
{ top: el.offsetTop, left: el.offsetLeft }

// $(el).offset();
const rect = el.getBoundingClientRect();

{
  top: rect.top + document.body.scrollTop,
  left: rect.left + document.body.scrollLeft
}

Binding events

// $(el).on(eventName, eventHandler);
el.addEventListener(eventName, eventHandler);

// $(el).off(eventName, eventHandler);
el.removeEventListener(eventName, eventHandler);

If working with a collection of elements, you can bind an event handler to each one of them by using a loop:

// $('a').on(eventName, eventHandler);
const links = document.querySelectorAll("a");

[].forEach.call(links, function (link) {
	link.addEventListener(eventName, eventHandler);
});

Although instead of doing that, you should probably look into the next topic: event delegation.

Event delegation

Can add to higher element and use 'matches' to see if specific child was clicked (similar to jQuery's .on):

// $('ul').on('click', 'li > a', eventHandler);
const el = document.querySelector("ul");

el.addEventListener("click", (event) => {
	if (event.target.matches("li")) {
		// event handling logic
	}
});

The event object

var node = document.getElementById("my-node");
var onClick = function (event) {
	// this = element

	// can filter by target = event delegation
	if (!event.target.matches(".tab-header")) {
		return;
	}

	// stop the default browser behaviour
	event.preventDefault();

	// stop the event from bubbling up the dom
	event.stopPropagation();

	// other listeners on this node will not fire
	event.stopImmediatePropagation();
};

node.addEventListener("click", onClick);
node.removeEventListener("click", onClick);

Mocking events

var anchor = document.getElementById("my-anchor");
var event = new Event("click");

anchor.dispatchEvent(event);

Animations

// $(el).fadeIn();
function fadeIn(el) {
	el.style.opacity = 0;

	var last = +new Date();
	var tick = function () {
		el.style.opacity = +el.style.opacity + (new Date() - last) / 400;
		last = +new Date();

		if (+el.style.opacity < 1) {
			(window.requestAnimationFrame && requestAnimationFrame(tick)) || setTimeout(tick, 16);
		}
	};

	tick();
}

Or, if you are only supporting IE10+:

el.classList.add("show");
el.classList.remove("hide");

.show {
	transition: opacity 400ms;
}

.hide {
	opacity: 0;
}

Looping over and filtering through collections of DOM elements

Note this is not necessary if you are using querySelector(All).

// $(selector).each(function (index, element) { ... });
const elements = document.getElementsByClassName(selector);

// option 1
[].forEach.call(elements, function (element, index, arr) { ... });

// option 2
Array.prototype.forEach.call(elements, function (element, index, array) { ... });

// option 3
Array.from(elements).forEach((element, index, arr) => { ... }); // ES6 ⚠️

Same concept applies to filtering:

// $(selector).filter(":even");
const elements = document.getElementsByClassName(selector);

[].filter.call(elements, function (element, index, arr) {
	return index % 2 === 0;
});

Note that :even and :odd use 0-based indexing.

Another filtering example:

var nodeList = document.getElementsByClassName("my-class");
var filtered = Array.prototype.filter.call(nodeList, function (item) {
	return item.innerText.indexOf("Item") !== -1;
});

Random utilities

// $.proxy(fn, context);
fn.bind(context);

// $.parseJSON(string);
JSON.parse(string);

// $.trim(string);
string.trim();

// $.type(obj);
Object.prototype.toString
	.call(obj)
	.replace(/^\[object (.+)\]$/, "$1")
	.toLowerCase();

Adding multiple `window.{onload, onerror}` events

(function () {
	function addWindowEvent(event, fn) {
		var old = window[event];
		if (typeof old !== "function") {
			window[event] = fn;
			return;
		}

		window[event] = function () {
			old.apply(window, arguments);
			fn.apply(window, arguments);
		};
	}

	window.addOnLoad = function (fn) {
		addWindowEvent("onload", fn);
	};

	window.addOnError = function (fn) {
		addWindowEvent("onerror", fn);
	};
})();

XMLHttpRequest (XHR)

Despite its name, XMLHttpRequest can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including file and ftp).

To get data data from the server:

const xhr = new XMLHttpRequest();

xhr.open("GET", "/url", true);
xhr.onload = function () {
	if (this.status === 200) {
		console.log("success!");
	} else {
		console.log("failed", this.status);
	}
};
xhr.send();

Post data back to the server is quite similar, the only difference is the method name (POST) when opening the connection and the setting of the headers:

const xhr = new XMLHttpRequest();

xhr.open("POST", "/url/post", true);
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
xhr.onload = function () {
	if (this.status === 200) {
		console.log("success!");
	} else {
		console.log("failed", this.status);
	}
};
xhr.send();

Alternative libraries

AJAX: Axios, Superagent
Animations: Animate.css, Move.js
Working with arrays, numbers, objects, strings, etc.: Lodash

Credits and further resources

http://youmightnotneedjquery.com/
https://css-tricks.com/now-ever-might-not-need-jquery/
https://plainjs.com/javascript/
https://github.com/nefe/You-Dont-Need-jQuery

Getting clever with Array#reduce

2017-09-06T00:00:00Z

Just wanted to list a handful of rather unusual yet interesting use cases for Array#reduce, as most of the examples out there involve adding numbers together, something along the lines of:

const numbers = [1, 2, 3, 4, 5];
const sum = numbers.reduce((acc, current) => acc + current, 0);

But there's much more to Array.prototype.reduce than summing numbers in a list.

Heads up: Note that this post is not JavaScript specific as these concepts apply to any language supporting reducing arrays.

Functional pipelines (aka: function composition)

We can use Array#reduce to compose functions. Just to recap, here's what composing functions means in Maths:

The same concept applies to programming: we can apply different functions to a value one after the other and get a result out of that composition.

Here's how we can compose functions using Array#reduce:

const double = (value) => 2 * value;
const triple = (value) => 3 * value;
const half = (value) => 0.5 * value;
const square = (value) => value * value;
const pipeline = [square, double, triple, half];
const initialValue = 5;
const finalValue = pipeline.reduce((accumulator, fn) => fn(accumulator), initialValue);

In this example, our pipeline determines the order of application for the functions because we are iterating over the pipeline array:

half(triple(double(square(x))));

which for the initial value of 5 results in:

half(triple(double(square(5)))) = 75;

This is similar to Bash's pipes, which let you use the output of a program as the input of another one.

In this sample script, we first list all of the files in the current directory, then filter out anything that is not a json file and finally delete the selected files:

ls | grep "\.json$" | xargs rm -f

We can rewrite this to use the same function composition notation as before:

rm(grep(ls));

Recursively flatten arrays

We can use Array.prototype.reduce to recursively flatten an array:

function flatten(arr) {
	return arr.reduce((acc, current) => {
		if (Array.isArray(current)) {
			return acc.concat(flatten(current));
		}

		return acc.concat(current);
	}, []);
}

Note how we boil down the argument to a new array, starting from an empty list and concatenating new values as we move forward.

This works even for really deep nested arrays like:

flatten([1, 2, [3, 5, [6, 5, 4, [7, 8, [9]]], 1]);

Re-implementing Lodash's `get` method

Let's consider this example:

const person = {
	name: "John Doe"
};
const address = person.address.street;

This is obviously gonna throw a TypeError exception as we are trying to access a property of undefined, which is not an object.

We use Lodash's get helper when querying an object for properties we are not sure exist. We can easily re-implement this helper using Array#reduce:

function get(obj, path, defaultValue) {
	return path.split(".").reduce((acc, field) => {
		if (acc[field]) {
			return acc[field];
		}

		return defaultValue;
	}, obj);
}

Let's now use it:

const person = {
	details: {
		name: {
			first: "John",
			last: "Doe"
		},
		email: "john@doe.com",
		dob: {
			day: 15,
			month: "January",
			year: 2017
		}
	}
};
const day = get(person, "details.dob.month.number", "bummer");
const month = get(person, "details.dob.day");
const year = get(person, "details.dob.year");

console.log("dob is", `${month} ${day}, ${year}`);
console.log("age is", get(person, "details.age", "/shrug"));

Side note: for the first example, we might as well play safe by doing:

const address = person.address && person.address.street;

However I find using get(person, 'address.street') to be much more concise. But it's just interesting to see how we'd go about reimplementing the utility library by using reduce.

Optimising chained operations for better performance

It's a common practice to chain multiple map, filter and reduce calls to the same array:

const numbers = [10, 5, 11, 20, 14, 15, 2, 3];
const result = numbers.filter((current) => current % 2 === 0).map((current) => 3 * current);

This is great in terms of readability as the intent of our code is super clear and easy to follow. However, bear in mind each time we chain one of these functions, not only we are creating a new array in memory on the process but we are also iterating again over the resulting list. This can have significant performance implications if we are dealing with massive collections.

For the example above, we can easily achieve the same result with a single call to Array#reduce by encapsulating the logic of the filter and map:

const result = numbers.reduce((acc, current) => {
	if (current % 2 === 0) {
		acc.push(3 * current);
	}

	return acc;
}, []);

This way we are only looping over the initial array once and no extra arrays are created in the process. Again, not a huge performance gain in this case with just one map and one filter, but could be quite significant if there are more operations chained and the initial collection is bigger.

Counting occurrences

For any list of recurring values, we can use Array.prototype.reduce to count how many times each value is present on our list.

const countries = ["AU", "NZ", "AU", "UK", "IE", "IT", "IE", "NZ", "CH", "UK", "IT", "AU", "NZ", "AU", "IT"];
const count = countries.reduce((acc, val) => {
	if (acc[val]) {
		acc[val] = acc[val] + 1;
	} else {
		acc[val] = 1;
	}

	return acc;
}, {});

In this case, we return an object in which keys are distinct countries and values are the number of occurrences for each country:

{
  AU: 4,
  CH: 1,
  IE: 2,
  IT: 3,
  NZ: 3,
  UK: 2
}

Adding multiple new nodes to the DOM

Consider the following code:

nodes.forEach((node) => document.body.append(node));

DOM injections and modifications are expensive, so it's important to keep these interactions to a minimum. Using fragments keeps recalculation of styles, painting and layout to a minimum. In this case, we could make use of DocumentFragment which acts as a pseudo DOM node and allows us to do exactly the same thing but in a more performant way:

const nodesInFragment = nodes.reduce((fragment, node) => {
	fragment.append(node);
	return fragment;
}, document.createDocumentFragment());

document.body.append(nodesInFragment);

I've seen some of these ideas on Mykola Bilokonsky's Egghead course and also on Twitter.

A simple Observable implementation

2017-08-06T00:00:00Z

Let's write our own Observable interface implementation to understand what's going on under the hood when we work with RxJS.

An observable is just a function. This function takes in an observer as an argument, and returns a subscription object.

An observer is just an object with three methods: next which takes in a value, error which takes in an error message and complete with has no arguments. This is what a standard (logging) observer looks like:

{
    next(value) {
        console.log(value);
    }, error(err) {
        console.error(err);
    }, complete() {
        console.info('done');
    }
}

A subscription object represents a disposable resource, such as the execution of an Observable. This subscription has a bunch of methods such as add and remove, but the most important one is unsubscribe which takes no argument and just disposes the resource held by the subscription. More on this later, when we get to the asynchronous examples.

When an Observable produces a value, it lets the observer know by calling next on the produced value, or error when a problem occurs.

This communication between the observable and the observer can terminate in two different ways:

the observer (consumer of values) decides it's no longer interested in receiving more values and it therefore unsubscribes from the observable by calling the unsubscribe function returned upon subscription.
the observable (producer of values) has no more values to send, and informs the observer by calling complete on it.

A synchronous `Observable` example: `Rx.Observable.from`

Let's try to recreate the following behaviour provided out of the box by RxJS. We'll create an observable that returns synchronously and immediately five values over time, and then completes.

const numbers$ = Rx.Observable.from([0, 1, 2, 3, 4]);

numbers$.subscribe(
	(value) => console.log(value),
	(err) => console.error(err),
	() => console.info("done")
);

Based on our previous definition of observable, we can rewrite our numbers$ stream from the ground up by using a function which takes an observer object as an argument, like this:

function Observable(subscribe) {
	this.subscribe = subscribe;
}

Observable.from = (values) => {
	return new Observable((observer) => {
		values.forEach((value) => observer.next(value));
		observer.complete();
		return {
			unsubscribe() {
				console.log("unsubscribed");
			}
		};
	});
};

const observer = {
	next(value) {
		console.log(value);
	},
	error(err) {
		console.error(err);
	},
	complete() {
		console.info("done");
	}
};

const numbers$ = Observable.from([0, 1, 2, 3, 4]);
const subscription = numbers$.subscribe(observer);

setTimeout(subscription.unsubscribe, 500);

The forEach statement is in charge of delivering our values synchronously. Immediately afterwards, we call the complete method to notify the observer we are done producing values.

By and large, what's going on here is the observable notifies the observer of all emitted values and right after the last value got pushed through, it lets the observer now it's done emitting.

Side note: here unsubscribing doesn't make much sense as values get delivered in a synchronous fashion. Just wanted to illustrate how a subscription object gets returned, and how we can unsubscribe at some point later in time.

A flaw in our implementation

Even though our implementation works, there's an edge case we haven't accounted for: we can keep emitting values even after having called complete. Try this:

Observable.from = (values) => {
	return new Observable((observer) => {
		values.forEach((value) => observer.next(value));
		observer.complete();
		observer.next("still emitting");

		return {
			unsubscribe() {
				console.log("unsubscribed");
			}
		};
	});
};

The observer will get notified of this last still emitting value, even though the observable has already told the observer it was done emitting values.

Let's tweak our implementation so that it stops emitting once unsubscribed from. For starters, we'll create some sort of observer wrapper with some basic validation logic, which also keeps track of whether it has already unsubscribed from the observable (this would be the observer state).

class Observer {
	constructor(handlers) {
		this.handlers = handlers; // next, error and complete logic
		this.isUnsubscribed = false;
	}

	next(value) {
		if (this.handlers.next && !this.isUnsubscribed) {
			this.handlers.next(value);
		}
	}

	error(error) {
		if (!this.isUnsubscribed) {
			if (this.handlers.error) {
				this.handlers.error(error);
			}

			this.unsubscribe();
		}
	}

	complete() {
		if (!this.isUnsubscribed) {
			if (this.handlers.complete) {
				this.handlers.complete();
			}

			this.unsubscribe();
		}
	}

	unsubscribe() {
		this.isUnsubscribed = true;

		if (this._unsubscribe) {
			this._unsubscribe();
		}
	}
}

One thing I'd like to highlight here is how we unsubscribe once either complete or error get called. This means not only we've fixed our implementation flaw, but we're also now unsubscribing when an error gets thrown. More on this here.

We also need to adjust our Observable function to make it work with this new Observer implementation.

class Observable {
	constructor(subscribe) {
		this._subscribe = subscribe;
	}

	subscribe(obs) {
		const observer = new Observer(obs);

		observer._unsubscribe = this._subscribe(observer);

		return {
			unsubscribe() {
				observer.unsubscribe();
			}
		};
	}
}

Side note: see how we are returning a subscription object after we subscribe? That's the reason why we can't keep on chaining operators after we call subscribe on a stream.

So, now that we've got our Observable and Observer helper classes, let's rewrite our example to make use of them:

Observable.from = (values) => {
	return new Observable((observer) => {
		values.forEach((value) => observer.next(value));
		observer.complete();

		return () => {
			console.log("Observable.from: unsubscribed");
		};
	});
};

const numbers$ = Observable.from([0, 1, 2, 3, 4]);
const subscription = numbers$.subscribe({
	next(value) {
		console.log(value);
	},
	error(err) {
		console.error(err);
	},
	complete() {
		console.info("done");
	}
});

setTimeout(subscription.unsubscribe, 500);

An asynchronous `Observable` example: `Rx.Observable.interval`

We've cover how Rx.Observable.from works. Let's now work with an asynchronous example, by recreating Rx.Observable.interval:

const interval$ = Rx.Observable.interval(1000);

interval$.subscribe({
	next(value) {
		console.log(value);
	},
	error(error) {
		console.error(error);
	},
	complete() {
		console.info("done");
	}
});

First things first: we want to be able to cancel the interval at some point. That's why we need to return some sort of cancellation logic (tear down logic, in terms of RxJS). For this we'll use clearInterval.

Observable.interval = (interval) => {
	return new Observable((observer) => {
		let i = 0;
		const id = setInterval(() => {
			observer.next(i++);
		}, interval);

		return () => {
			clearInterval(id);
			console.log("Observable.interval: unsubscribbed");
		};
	});
};

const observer = {
	next(value) {
		console.log(value);
	},
	error(err) {
		console.error(err);
	},
	complete() {
		console.info("done");
	}
};
const interval$ = Observable.interval(100);
const subscription = interval$.subscribe(observer);

setTimeout(subscription.unsubscribe, 1000);

The cancellation of the subscription happens a second after the observable started emitting, meaning we'll get 10 values delivered every 100 milliseconds.

Also, complete never gets called because this is an infinite stream — values are infinitely available as they are coming from setInterval.

Observing (asynchronous) DOM Events: `Rx.Observable.fromEvent`

Let's now observe DOM events. This is how you'd go about it in RxJS:

const button = document.getElementById("btn");
const clicks$ = Rx.Observable.fromEvent(button, "click");

clicks$.subscribe({
	next(value) {
		console.log("clicked");
	},
	error(error) {
		console.error(error);
	},
	complete() {
		console.info("done");
	}
});

Let's add this functionality to our Observable class:

Observable.fromEvent = (element, eventName) => {
	return new Observable((observer) => {
		const eventHandler = (event) => observer.next(event);

		element.addEventListener(eventName, eventHandler, false);

		return () => {
			element.removeEventListener(eventName, eventHandler, false);
			console.log("Observable.fromEvent: unsubscribbed");
		};
	});
};

Same as before, we are attaching an event listener upon subscription via addEventListener, and tearing it down when we unsubscribe by using removeEventListener.

In this example we are only listening for click events for the first 1.5 seconds, and we unsubscribe afterwards.

const clicks$ = Observable.fromEvent(button, "click");
const subscription = clicks$.subscribe({
	next(value) {
		console.log("clicked");
	},
	error(err) {
		console.error(err);
	},
	complete() {
		console.info("done");
	}
});

setTimeout(subscription.unsubscribe, 1500);

Operators

So far we've talked about creating observables from different sources, but we haven't touched on operators which are the bread and butter of functional reactive programming.

Let's recreate the functionality provided by map. What map does is to apply a transformation function to every value pushed down the stream.

Site note: operators always return new streams, which allows chaining on other operators.

Observable.prototype.map = function (transformation) {
	const stream = this;

	return new Observable((observer) => {
		const subscription = stream.subscribe({
			next: (value) => observer.next(transformation(value)),
			error: (err) => observer.error(err),
			complete: () => observer.complete()
		});

		return subscription.unsubscribe;
	});
};

Note that this is the observable we called map on (we have access to it because map is a prototype method).

Credits

I've written this post after watching this lesson by Ben Lesh.

Also, here's a jsbin I've put together so you can play a little bit with this.

DOM & BOM revisited

2017-08-06T00:00:00Z

Let's go back to the basics and briefly review two important JavaScript concepts: the DOM and the BOM.

DOM

The Document Object Model (DOM) is a set of utilities for manipulating XML documents (and, by extension, also HTML documents, which is what we are most likely interested in).

Before being able to make use of these utilities and helpers, DOM transforms XML files into a tree structure, that is, a hierarchy of nodes. This tree represents both the content of the document and the relationship between the nodes.

Node types

Note how in the example above we've got different node types: most of them are labelled as Element, but others are marked as Attribute or Text instead. The DOM defines different types of nodes which implement different interfaces. Here's a list of the most common node types:

Document which is the root node of all XML (HTML) documents.
DocumentType which represents the document type definition (DTD) used on the page (doctype tag)
Element which represents a tag
Attr which is a key-value pair representing an attribute for a tag.
Text which represents the content of a node.
Comment which represents XML/HTML comments.

The `Node` interface

A Node object implements and exposes the following properties and methods. You can find a thorough list on MDN.

nodeName
nodeValue
nodeType
ownerDocument
firstChild
lastChild
childNodes
previousSibling
nextSibling
hasChildNodes()
attributes
parentNode
parentElement
appendChild(node)
removeChild(node)
replaceChild(newNode, previousNode)
insertBefore(newNode, previousNode)

Accessing nodes

The easiest way to get hold of nodes is by referencing them directly using one of the following methods:

document.querySelector(selector): Element where selector is something in the lines of #some-id, .some-classname, or tag. If there are multiple elements matching the selector, you'll only get the first one returned.
document.querySelectorAll(selector): NodeList
document.getElementById(id: string): Element
document.getElementsByClassName(classname: string): HTMLCollection
document.getElementsByTagName(tag: string): HTMLCollection
document.getElementsByName(name: string): NodeList

We can also use most of these methods (except getElementById and getElementByName) on any node of type Element which acts as the root element for our query:

const wrapper = document.querySelector("#wrapper");

wrapper.getElementsByTagName("p");
wrapper.getElementsByClassName("active");
wrapper.getElementsByName("something");

See how some methods return a NodeList whereas others return a HTMLCollection? An HTMLCollection is always live, which means that changes to the DOM are reflected in the collection. A NodeList, on the other hand, can be either live or static. document.querySelectorAll returns a static NodeList, meaning any subsequent changes to the DOM won't be reflected in the collection (ie: the static NodeList object).

A note on performance: In some browsers there are significant performance costs for using querySelectorAll instead of, for instance, getElementsByTagName. This is because a static NodeList needs to have all the necessary data upfront, whereas a live NodeList can be generated and returned much quickly.

Moving on... We can also make use of most of the properties of the Node interface to traverse the document object by specifying the path all the way down to the node we are trying to grab. For instance:

document.documentElement.lastChild;
document.documentElement.childNodes[0];
document.documentElement.firstChild.nextSibling;
document.body.previousSibling;
document.body.parentNode;

Side note: in most cases, parentNode and parentElement return the same thing. They only differ when the parent node is not of type Element, in which case parentElement will return null. For instance:

// both return the html element
document.body.parentNode === document.body.parentElement; // true

document.documentElement.parentNode; // returns the document node
document.documentElement.parentElement; // returns null

Another quick aside, this time on the difference between document and document.documentElement. The latter returns the html element, which is most likely what you are after if you are trying to traverse the DOM. Also, they have different node types assigned:

document.nodeType; // 9 = DOCUMENT_NODE
document.documentElement.nodeType; // 1 = ELEMENT_NODE

Attributes

DOM nodes of type Element expose an attributes property of type NamedNodeMap which is a collection of all attributes for a particular element.

const element = document.querySelector("#title");
const className = element.attributes.class; // dot notation
const firstAttribute = element.attributes[0]; // array notation

Note that any element within the attributes collection is an object of type Node for which nodeType = 2, ie: ATTRIBUTE_NODE.

element.attributes.class.nodeType; // returns 2 = ATTRIBUTE_NODE

We can get, set and remove attributes by using these methods:

element.getAttribute('class')
element.setAttribute('class', 'new-classname')
element.setAttributeNode(attributeNode)
element.removeAttribute('class')

The DOM HTML specification allows accessing and modifying all attributes directly by assigning new values:

<img src="image.jpg" alt="This is an image" class="logo logo-sm" />

const image = document.querySelector(".logo");

image.src; // returns "image.jpg"
image.alt = "Rawr"; // updates the alt text

This holds true for all attributes except for class . This is because class is a reserved keyword put into use as of ES6. That's why we need to use the alternative attribute name className instead. The same principle applies to the for attribute in the label element, where we use htmlFor instead.

image.className; // returns "logo logo-sm"
image.class; // returns undefined

Note that for CSS classes we have also got access to the classList property which is a collection of type DOMTokenList that lists all of the element classnames. This interface implements four important methods: add, remove, toggle and contains.

image.classList; // returns ["logo", "logo-sm"]image.classList.add('logo-awesome');

image.classList.remove("logo-sm");
image.classList.toggle("active");
image.classList.contains("this-class-doesnt-exist");

image.classList; // now returns ["logo", "logo-awesome", "active"]

One more thing, this time about listing all computed CSS properties of an element. There's a method called window.getComputedStyles(element) you pass in your element to and returns a massive object of type CSSStyleDeclaration you can use to figure out the computed styles of an element, no matter how they got applied.

getComputedStyle(image).width; // returns the actual image width

Creating, removing and replacing Nodes

There are different factory methods attached to the document object we can use to create nodes of different types. Most common ones are:

document.createElement(tag: string): returns a node of type Element
document.createAttribute(name: string): returns a node of type Attr
document.createTextNode(text: string): returns a node of type Text
document.createComment(comment: string): returns a node of type Comment

Some examples:

const p = document.createElement("p");
const blurb = document.createTextNode("sup mate");
const attr = document.createAttributeNode("class");

p.appendChild(blurb);
attr.value = "my-custom-class";
p.setAttributeNode(attr);
p.setAttribute("is-awesome", true);

To remove nodes, use the removeChild method by querying the parent first. removeChild takes the element we are trying to remove as a param.

There's also the remove method we can use on elements, although it's not supported on Internet Explorer and needs to be polyfilled.

const element = document.querySelector("#title");

element.parentNode.removeChild(element);
element.remove(); // this doesn't work on IE!

We can replace a node via the replaceChild method. It's kind of the same process we'd use to remove a node: we query the parent node first, then we call the replaceChild method on the parent passing in the newElement first and the oldElement (the one we are trying to replace) as the second param, and we end up getting the replaced node back.

const oldElement = document.querySelector("#title");
const newElement = document.createTextNode("this is our new title");
const newElementText = document.createTextNode("our new title");

newElement.appendChild(newElementText);

const replacedNode = oldElement.parentNode.replaceChild(newElement, oldElement);

replacedNode === oldElement; // true

Node relationships

There are a bunch of ways for setting a relationship between two nodes:

element.append
element.appendChild
element.insertBefore
element.insertAdjacentElement

Events

Each HTML element has its own list of supported events types. We listen for events on an element, and whenever the event is triggered we handle it through a function called event handler.

One element can listen and respond to multiple event types.
One event type can be handled by multiple elements.

You can bind event handlers to elements via the addEventListener method. First argument is the event name, second one is the event handler:

const button = document.querySelector("#button");

function handleClick(event) {
	console.log("clicked");
}

button.addEventListener("click", handleClick);

Our event handler function receives an event object passed in as a param.

To stop listening for an event on an particular element, use the removeEventListener method on it:

button.removeEventListener("click", handleClick);

There's a catch, though. To remove event handlers, the handler function needs to be a named function, you need to keep a reference to the function handling the event. In other words, this means anonymous functions won't work if you are planning on removing the listener later on.

Here's a list with some of the most widely used event types:

Mouse events: click, dblclick, mousedown, mouseout, mouseover, mouseup, mousemove.
Keyboard events: keydown, keypress, keyup.
HTML events: load, unload, abort, error, resize, change, submit, reset, scroll, focus, blur.
DOM events: DOMSubtreeModified, DOMNodeInserted, DOMNodeRemoved.

For a more extensive list of event types check out this link.

BOM

The Browser Object Model (BOM) allows JavaScript to talk to the browser about matters other than the content of the page.

There are no official standards for the BOM, albeit browser vendors have implemented almost the same features for interoperability.

The `window` object

The window object is the very root element, everything else is attached to it either directly or indirectly. Hence there's no need to reference it explicitly.

In tabbed browsers, each tab owns its own window object, ie: it is not shared between tabs in the same window.

Also, all of the variables and functions that don't get attached to any other object, get attached to the window object and are then within the global scope. In other words: global variables become properties of the window object, whereas global functions become methods of the window object.

The window global object provides access to:

properties which provide info on the browser's window:

// outer dimensions
const outerHeight = window.outerHeight;
const outerWidth = window.outerWidth;

// inner dimensions
const innerHeight = window.innerHeight;
const innerWidth = window.innerWidth;

methods for setting timers and to repeatedly call a function:

const timeout = setTimeout(callback, delay); // delay in ms
const interval = setInterval(callback, delay); // delay in ms

clearTimeout(timeout);
clearInterval(interval);

And many more. Here's a full list of all of the properties and methods of the global window object.

The `location` object

Because of the lack of an standard, we've got the location object attached to both document and window:

document.location === window.location; // returns true

This objects allows for reading and manipulating the URL on the browser's address bar. Here's a list of all of the major properties and methods it exposes (a more extensive list can be found here):

location.hash
location.host
location.hostname
location.href returns the full URL of the current page. We can also write to this property, causing a redirect to the new value.
location.pathname returns whatever comes after the hostname.
location.port returns the port number but only if it's set on the URL.
location.protocol returns the protocol used to access the page.
location.search returns whatever comes after the ? in the URL.
location.assign(url) navigates to the url passed in as a param.
location.replace(url) is similar to assign, but the replaced site gets removed from the session history.
location.reload() which has the same effect as clicking the reload button on our browser.

More info on the Location interface on MDN.

The `history` object

window.history allows to manipulate the browser session history, that is the pages visited in the tab or frame that the current page is loaded in.

history.length returns an integer representing the number of elements in the session history, including the currently loaded page.
history.go(integer) redirects to the page in the session history identified by its relative location to the current page.
history.back(integer) redirects to the previous page in the session history, same as clicking the browser's Back button.
history.forward(integer) redirects to the next page in the session history, same as clicking the browser's Forward button.

More info on the History interface here.

The `navigator` object

window.navigator provides info on the state and identity of the user agent or UA (that is, the browser and OS the user is running).

navigator.userAgent returns the user agent for the current browser.
navigator.language returns a string representing the preferred language of the user, usually the language of the browser UI.
navigator.languages returns an array of the languages known to the user, sorted by preference: ["en-GB", "en-US", "en"]
navigator.getBattery() returns a promise which is resolved into a BatteryManager object providing not only information about the system's battery but also some events you can handle to monitor the battery status.
navigator.plugins returns a list of the plugins installed in the browser.
navigator.onLine returns a boolean indicating whether the browser is working online.
navigator.geolocation returns a Geolocation object allowing accessing the location of the device.

There are also some other properties available we can't always rely on:

navigator.appName should return the browser's name.
navigator.appVersion should return the browser's version number.
navigator.plaftorm should return the browser's platform name.

That wraps it up for this DOM and BOM high-level overview. Please refer to the MDN site for further and more detailed content. Thanks for reading!

Arrays, objects and mutations

2017-03-06T00:00:00Z

Here are some thoughts on how to avoid mutations when working with arrays and objects in JavaScript by treating them as if they were immutable data structures.

What's a mutation?

An immutable value is one that, once created, can never be changed. In JavaScript, primitive values such as numbers, strings and booleans are always immutable. However, data structures like objects and arrays are not.

By mutation I mean changing or affecting a source element. The goal is to keep the original element unchanged at all times.

A mutation is a side effect: the fewer things that change in a program, the less there is to keep track of, which results in a simpler program.

I've marked techniques which involve a mutation to the source element with a ❌ whereas immutable methods are marked with a ✅.

Adding new elements to an array

Array.prototype.push ❌
Array.prototype.unshift ❌
Array.prototype.concat ✅
Spread Operator (ES6) ✅

Array.prototype.push allows us to push elements to the end of an array. This method does not return a new copy, rather mutates the original array by adding a new element and returns the new length property of the object upon which the method was called.

const numbers = [1, 2];
numbers.push(3); // results in numbers being [1, 2, 3]

There's also Array.prototype.unshift which we can use to add elements to the very beginning of an array. Just as push, unshift does not return a new copy of the modified array, rather the new length of the array.

const numbers = [2, 3];
numbers.unshift(1); // results in numbers being [1, 2, 3]

In these two examples we are mutating or changing the original array. Remember, the goal is to keep the source array untouched. Let's go through some alternatives to adding new elements to an array without altering the source.

Perhaps the easiest way out would be to create a copy of the source array and push directly to it:

const numbers = [1, 2];
const moreNumbers = numbers.slice();
moreNumbers.push(3);

We could call this a "controlled mutation" as we are indeed mutating an array, although not the original one, but a copy we created for this purpose. However, Array.prototype.slice can be tricky as it does not create a deep clone, rather a shallow copy of the source array.

Array.prototype.concat does indeed return a new array, which is what we are after. We can make use of this method to return a new array with an extra element (or elements) appended to the original one:

const numbers = [1, 2];
const moreNumbers = numbers.concat([3]);

Just a little heads up: concat also returns a shallow copy of the source array (just as slice does). This means that it only copies the references to both objects and other arrays within our original list. Shall you want to have a complete brand new copy of your array, consider using Lodash's cloneDeep which recursively clones the array or object passed in as a param:

const people = [{ name: "Bob" }, { name: "Alice" }];
const morePeople = cloneDeep(people).concat([{ name: "John" }]);

console.log(people[0] === morePeople[0]); // returns false

Shallow copies vs deep clones is a recurrent topic throughout this post. Remember to always use cloneDeep if the elements of your source array are other arrays or objects and you need to keep them untouched. However, bear in mind deep cloning is an expensive operation in terms of performance. You might not always need a deep clone — in fact, and as a rule of thumb, you should probably avoid creating deep clones as long as you can: just consider whether you really need them and, in case you do, be aware of the tradeoffs.

Going back to adding new elements to an array in an immutable way, we could also use the spread operator, available since ES6, as a replacement to concat:

const numbers = [1, 2];
const moreNumbers = [...numbers, 3];

So far we have added elements either to the very beginning or very end of the array, but it's also possible to add elements to any position by using Array.prototype.splice. Bear in mind splice changes the source array.

const positions = ["First", "Second", "Fifth", "Sixth", "Seventh"];
positions.splice(2, 0, "Third", "Fourth");

In this example, the second argument (0) means "do not remove anything".

Again, we can achieve the same thing without mutating the original array by using concat:

const positions = ["First", "Second", "Fifth", "Sixth", "Seventh"];
const morePositions = positions.slice(0, 2).concat(["Third", "Fourth"]).concat(positions.slice(2));

And once again, the spread operator gets the job done as well:

const positions = ["First", "Second", "Fifth", "Sixth", "Seventh"];
const morePositions = [...positions.slice(0, 2), "Third", "Fourth", ...positions.slice(2)];

Adding new properties to an object

Direct addition ❌
Object.assign (ES6) ✅
Object spread operator (experimental, not yet standardised) ✅

We can easily add new properties to an object by setting them directly. Of course, this constitutes a mutation to the original object:

const person = { name: "John Doe", email: "john@doe.com" }; // Using dot notation
person.age = 27; // Using array notation
person["nationality"] = "Australian";

Probably the most widespread solution to add further properties without changing the source object is to use Object.assign or Lodash's assign (they both have the same signature):

const person = { name: "John Doe", email: "john@doe.com" };
const samePerson = Object.assign({}, person, {
	age: 27,
	nationality: "Australian"
});

A note on Object.assign: see how the first argument is a new, empty object? Well, it's important to know Object.assign mutates the first parameter you pass on to it. That's why I'm passing {} and not person as the first argument, as I don't want person to be modified by this operator. The takeaway here is to always pass in an empty object as the first param if you want to keep the source objects untouched.

Similarly to what happens with arrays, we can make use of the object spread operator which by the way is not yet standardised. The object spread operator is conceptually similar to the ES6 array spread operator.

const person = { name: "John Doe", email: "john@doe.com" };
const samePerson = { ...person, age: 27, nationality: "Australian" };

Removing elements from an array

Array.prototype.splice ❌
Array.prototype.pop ❌
Array.prototype.shift ❌
Array.prototype.slice & Array.prototype.concat ✅
Array.prototype.slice & the ES6 Spread Operator ✅
Array.prototype.filter ✅

Array.prototype.splice(index, number) removes number elements starting from index, and returns an array of the removed elements.

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
cities.splice(2, 1); // removes 1 element from the 2nd index (Cork)

Array.prototype.pop can be used to remove elements from the end of the array. It also returns the removed element. This is kind of the inverse function of Array.prototype.push.

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const bern = cities.pop(); // removes Bern from the list of cities

Then we've got Array.prototype.shift which removes the first element of an array and returns it as well. This would be the inverse function of Array.prototype.unshift.

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const oslo = cities.shift(); // removes Oslo from the list of cities

splice, pop and shift all mutate the source array. Let's now go through some techniques to keep the original array untouched.

Let's say we want to derive a capitals array from the list of cities in the previous examples, meaning we need to remove Cork and keep all of the others. To achieve this we can use a combination of slice and concat to create a copy of a slice of the source array (from the beginning up to the second element, which is not included) and then concatenating it with another slice of the original array, this time from the third position onwards. This way we got rid of the element at the second index (in this case, Cork).

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const capitals = cities.slice(0, 2).concat(cities.slice(3));

We can achieve the same thing using the spread operator:

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const capitals = [...cities.slice(0, 2), ...cities.slice(3)];

We could also use Array.prototype.filter to filter out the element (or elements) we want to get removed. This method returns a new array.

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const capitals = cities.filter((city) => city !== "Cork");

We can also filter by index:

const cities = ["Oslo", "Rome", "Cork", "Paris", "London", "Bern"];
const capitals = cities.filter((city, index) => index !== 2);

Removing properties from an object

delete operator ❌
Object destructuring ✅
Lodash's pick and omit ✅

We can remove properties from an object by using the delete operator. This, of course, changes or mutates the source object.

const person = { name: "John Doe", email: "john@doe.com", age: 27 }; // dot notation
delete person.age; // array notation
delete person["age"];

In order to avoid mutations we can easily use the ES6 spread operator (object destructuring):

const person = {
	name: "John Doe",
	email: "john@doe.com",
	age: 27,
	country: "Australia",
	language: "English",
	profession: "Front End Developer"
};
const { profession, country, ...newPerson } = person;

console.log(newPerson);

where profession and country are the properties we want removed from the new object.

We can also resort to Lodash's pick and omit. They both have the same signature: first argument is the object you are gonna work on, whereas the second one can be either a string or an array of strings of the property or properties we want preserved or removed. They both return a new object.

const person = { name: "John Doe", email: "john@doe.com", age: 27 };
const fewerDetails = _.omit(person, "age"); // or we could use pick which is the inverse of omit
const fewerDetails = _.pick(person, ["name", "email"]);

The takeaway

There are contexts in which mutation is not allowed (e.g. Redux reducers), but it's fine in many other cases. This is why it's essential to differentiate between observable and unobservable mutations. If you create an object in a function and then just need to populate it, it's not very clever to try to avoid a mutation, let alone very inefficient. This thread is a good read on the topic.
Remember that the spread operator, Array.prototype.concat, Array.prototype.slice, etc. they only return a shallow copy of the array. If this is not good enough for your use case, use Lodash's cloneDeep.
Also remember that returning a new array/object instead of mutating the original one, and particularly deep clones, are expensive in terms of performance. Just be aware that keeping data structures immutable comes with a price.

Credits

This post is heavily inspired on the need to keep state immutable on Redux reducers and touches on concepts taught by Dan Abramov on his Redux course.

A look at the inner workings of Redux

2017-02-01T00:00:00Z

This article is not about explaining how to bring Redux into your own React application, there are heaps of tutorials touching on that already. Let's rather try to understand what's really going on under the hood when we use Redux by implementing a simplified version of it from scratch.

TL;DR

Don't feel like reading the whole thing? You can find the code for this article here. The src/lib folder holds a rough re-implementation of both the redux and react-redux libraries.

The need for Redux

Have you ever needed to display a loading spinner in your application, and found yourself passing in a callback two or three levels down your component hierarchy to have the spinner displayed when appropriate?

Communicating React components is fairly straightforward when we've got a parent-child relationship, but can quickly get messy if we are trying to communicate components within different levels down the tree hierarchy.

For communication between two components that don't have a parent-child relationship, you can set up your own global event system. Subscribe to events in componentDidMount(), unsubscribe in componentWillUnmount(), and call setState() when you receive an event. The Flux pattern is one of the possible ways to arrange this. — React docs

This is what Redux is for. Whenever Redux is involved, container components don't communicate directly between each other by passing in callbacks and props down the tree.

This is the rough flow proposed by Redux:

Components are given callback functions as props, which they call whenever a UI event happens.
Those callbacks create and dispatch actions based on the event.
Reducers process the actions, computing the new state.
The new state of the whole application goes into a single store.
Components receive the new state as props and re-render themselves where needed.

State Tree

Redux is a (predictable) state container for our application, and the state tree is the minimum representation of our application state at any given time.
There is only one state tree that holds the state for the whole application. This means there's a single source of truth for our data/state.
The state tree lives within the application store. More on this later.
The state tree is read only, meaning we cannot modify or write to it directly. The only way to change it is by dispatching actions.

Actions

An action is a plain JavaScript object that describes in a minimal way what needs to get updated in the application state. Actions are a way to trigger state mutations: they describe what should change, albeit having no idea how to make that change.

Whether it is initiated by a network request or by user interaction via the UI layer, any data that gets into the Redux store gets there through an action. This means an action can be trigged in response to some user interaction (e.g.: click on a button) but also by the completion or failure of some asynchronous operation, such as a network call.

Actions are identified by a string called action type. This identifier is mandatory, and naturally it's required to be unique. Action types are strings because they need to be serialisable.

Actions can optionally carry some sort of payload or data required by the corresponding reducer to successfully mutate the state.

function displayAlert() {
	return {
		type: "DISPLAY_ALERT",
		payload: {
			message: "Something went wrong"
		}
	};
}

By the way, this particular example follows the Flux Standard Action pattern. This is of course optional but I found it to be a nice way to describe your actions keeping them consistent throughout the application.

Reducers

Reducers are pure functions which describe state mutations. Unlike actions, reducers do know how to have things changed in the application state, they do know the implementation details for those changes.

The signature for a reducer function is as follows:

function someReducer(previousState, action) {
	return nextState;
}

where state is the current application state, action is the action object which has triggered the state mutation (containing an action type and any relevant payload) and nextState is the resulting computed state of the app which can be derived from the other two arguments.

Store

The store is the glue that holds all of the Redux building blocks together: the state tree, the action dispatcher and the application reducers. And as such, there can only be a single instance of the store in a Redux app.

Once instantiated, the store exposes three important methods:

`store.getState()`

The store holds the state object (aka: state tree). This getState method retrieves and returns the current state of the Redux store (that is, the current state tree). If we haven't triggered any action yet, getState will return the initial state of our application.

console.log(store.getState()); // returns the state tree

`store.dispatch(action)`

The application store allows us to trigger actions in order to have the state of our application changed by exposing a dispatch method. We only need to pass in a valid action object to it, and the store will take care of the rest.

store.dispatch({ type: "SHOW_SPINNER" });

`store.subscribe(callback)`

The store also keeps track of all of those who have subscribed to changes in the state tree. The subscribe method allows us to register a callback that will be run any time an action is dispatched causing the state tree to update. In Reactland (or any other declarative UI library) we can leverage this to trigger a re-render of our view layer.

Note that the subscribe method returns an unsubscribe function we can call later on to have ourselves removed from the list of listeners. Calling this unsubscribe function means we will no longer be notified when something changes in the state tree (i.e.: we stop observing the Redux store).

const unsubscribe = store.subscribe(callback);
unsubscribe();

Only those components that need to be aware of state changes should subscribe to the store, and that's why we usually make a distinction between presentational and container components. More on this later.

Implementing `createStore` from scratch

Redux is shipped with a createStore method we need to use in order to instantiate our application store.

const store = createStore(rootReducer);

The first argument it takes is a reducer (a single one) that describes how the global state gets updated for each particular action. We call this top-level reducer or root reducer.

description: even though rootReducer is a single reducer function, we can still combine multiple reducers into a single one. More on this later.

This is a rough implementation of createStore:

function createStore(reducer) {
	let state;
	let listeners = [];

	const getState = () => state;

	const dispatch = (action) => {
		state = reducer(state, action);
		listeners.forEach((listener) => listener());
	};

	const subscribe = (listener) => {
		listeners.push(listener);

		return () => {
			listeners = listeners.filter((l) => l !== listener);
		};
	};

	dispatch({ type: "@@redux/INIT" });

	return {
		getState,
		dispatch,
		subscribe
	};
}

Let's briefly go through what's going on here:

we've got two private variables: state which holds our state tree, and listeners which is an array that keeps track of all of the callbacks we need to run when our state tree changes.
we've got three functions which we expose: first one is getState() which returns the current state tree; second one is dispatch(action) which allows us to trigger actions in order to update the application state; and finally subscribe(callback) which allows us to register observers who will get notified whenever the state tree changes.
we dispatch an init action: when a store is created, an initialisation action is dispatched in order to have the state tree populated with the initial values set on each of our reducers. The @@redux prefix indicates system actions triggered by Redux itself.

Reducer composition pattern

Right now our rootReducer looks something like this:

const initialState = {
	count: 0,
	alert: {
		visible: false,
		message: ""
	}
};

function rootReducer(state = initialState, action) {
	switch (action) {
		case "COUNTER/INCREMENT":
			return Object.assign({}, state, { count: state.count + 1 });
		case "COUNTER/DECREMENT":
			return Object.assign({}, state, { count: state.count - 1 });
		case "ALERT/SHOW":
			return Object.assign({}, state, {
				alert: { visible: true, message: action.payload.message }
			});
		case "ALERT/HIDE":
			return Object.assign({}, state, {
				alert: { visible: false, message: "" }
			});
		default:
			return state;
	}
}

It handles all possible actions into a single place. This might work just fine if you only have a bunch of actions, but it's certainly not scalable.

Reducer composition means that a reducer can call or be called by another reducer. This is useful as it allows us to move from a single, gigantic reducer handling all possible (unrelated) actions to a set of specialised, independent reducers focusing on a single part of our application state.

As a result, our top level reducer will be made out of a bunch of other smaller reducers. Note that there is still a single top level reducer managing the state of your app, we just broke it down into smaller chunks. When we instantiate our store using createStore, however, we need to pass in a single reducer as a param.

Here's an example of what we mean by using the reducer composition pattern to delegate managing different parts of the state tree to other reducers.

const rootReducer = (state, action) => ({
	count: counterReducer(state.counter, action),
	alert: alertReducer(state.alert, action)
});

Some important things to note here:

The first time this runs, state.counter and state.alert will both be undefined. This means reducers will end up returning their corresponding initial value, thus populating the store for the first time.
The object returned by rootReducer shapes our state tree. In this case, it will be an object having two properties: counter and alert. The shape of the state tree is up to you: it can be a primitive, an array, an object, an Immutable.js structure, anything.
When an action comes in, all of our specialised reducers get called every single time... all of them! Only those reducers knowing how to handle this action will return an updated model, while the rest will return their current state. This is why it's important for all reducers to return their current state as the default case. The image below illustrates this fact:

A built-in reducer composition solution

The combineReducers helper gets shipped with Redux. It only takes one argument: an object. This object lets us configure the mapping between the state tree field names, and the reducers managing them.

import { combineReducers } from "redux";
import { counter, alert } from "./reducers";

const rootReducer = combineReducers({
	count: counter,
	alert
});

This combineReducer call translates to: "our state tree consists of two different properties, count and alert, which will be handled by the counter and alert reducers respectively".

Let's now rewrite combineReducers from scratch. combineReducers is a function whose only argument is the mapping between the state keys and the reducers. The returned value is supposed to be a reducer itself, therefore its signature must match the reducer signature: f(state, action).

Here's what a rough implementation of combineReducers:

const combineReducers = (reducers) => {
	return (state = {}, action) => {
		return Object.keys(reducers).reduce((nextState, key) => {
			nextState[key] = reducers[key](state[key], action);
			return nextState;
		}, {});
	};
};

Again, some things worth noting here:

We calculate the next state for any given key by calling the corresponding reducer. See how all reducers always run whenever an action gets triggered?
If you have a look at the second parameter of the reduce method, nestState starts off being an empty object and we gradually attach properties to it when running nextState[key] = ....
Finally, we are mutating the nextState object on each iteration. This is not a problem though, because we are mutating an object we have created ourselves inside the reducer, it isn't something we got passed in from the outside, meaning it's still a pure function.

Presentational vs Container Components

We have been talking about presentational and container components. Here's a brief description of what we mean when talking about those.

Presentational components:

Are concerned with how things look.
Also referred to as “dumb components” as they only display data.
Usually have DOM markup and styles of their own.
Have no dependencies on the rest of the app, such as Redux actions or stores.
Don't specify how data is loaded or mutated.
Receive data and callbacks exclusively via props.
Rarely have state of their own, and when they do it's just UI state rather than actual data, for instance something like “the menu is collapsed or expanded” for an accordion component.
Can be written as functional components unless they need state, lifecycle hooks, access to ref or performance optimisations.
May contain both presentational and container components that can be rendered via this.props.children.

Container Components:

Are mostly concerned with how things work.
Also referred to as “smart components” as they can trigger state mutations by dispatching actions.
Don't usually have much DOM markup/styles of their own except for a few wrapping divs.
Provide data and behaviour (callbacks) to presentational components.
Are often stateful, as they tend to serve as data sources.
Can contain both presentational and container components.

Now, when should we introduce new containers? As a rule of thumb, start building your app exclusively with presentational components. Eventually you'll realise that you are passing down too many props through intermediate components. When you notice that there are components which don't use the props they receive and rather forward them to their children, and when you have to rewire all those intermediate/bridging components any time some child needs more data, that's a clear indicator you might be needing to introduce a container component. This way you can get the data and the behaviour props to the leaf components without burdening the unrelated components in the middle of the tree.

Connecting container components to the store

Possibly the simplest way to have a component access the store to read the state tree, trigger actions and subscribe to state changes is to directly reference it, something in the lines of:

import { getState, dispatch, subscribe } from "./store";

class Counter extends React.Component {
	componentDidMount() {
		this.unsubscribe = subscribe(this.forceUpdate);
	}

	componentWillUnmount() {
		this.unsubscribe();
	}

	render() {
		return (
			<div>
				<p>{getState().count}</p>
				<button onClick={() => dispatch({ type: "INCREMENT" })}>Increment counter</button>
			</div>
		);
	}
}

This is not maintainable for two main reasons:

Testing: this approach prevents us from providing mock store instances.
Server-side Rendering (SSR): when building universal (isomorphic) applications we need to provide a different store instance for every request because different requests involve different data.

An alternative solution would be to pass the store down from the root component:

ReactDOM.render(<App store={store} />, document.querySelector("#root"));

making our Counter component look like this:

class Counter extends React.Component {
	componentDidMount() {
		const { subscribe } = this.props.store;

		this.unsubscribe = subscribe(this.forceUpdate);
	}

	componentWillUnmount() {
		this.unsubscribe();
	}

	render() {
		const { getState, dispatch } = this.props.store;

		return (
			<div>
				<p>{getState().count}</p>
				<button onClick={() => dispatch({ type: "INCREMENT" })}>Increment counter</button>
			</div>
		);
	}
}

This works just fine for shallow component trees. However, if all of our components need to pass down the store to their children, this quickly gets messy and complex. We can do better!

Introducing `react-redux`

Since connecting container components to the store is a recurrent problem every React+Redux app faces, the Redux authors came up with some sort of standard solution. They worked on a package called react-redux which provides a handful of React bindings for Redux. This means this library provides all of the tools we need to integrate our React app with Redux, particularly these two:

<Provider>, a React component
connect, a higher-order React component (HOC)

Just a side note about why we need two different projects, instead of having these live within the Redux package. Even though Redux was built with React in mind, it's actually a view-layer agnostic state management solution. People are using Redux with Angular or Vue. Hence it makes sense for these tools to live outside of the Redux project.

Using `Provider` to pass the store down to all children components

The react-redux library provides a <Provider> component whose job is to pass down the store to all of the connected components no matter how deep they are down the component tree.

This way we don't need to pass the store as a prop to our children: Provider does this for us automagically… well, sort of. It actually makes use of React's context feature:

By adding childContextTypes and getChildContext to the context provider, React passes the information down automatically and any component in the subtree can access it by defining contextTypes. If contextTypes is not defined, then context will be an empty object. — React docs

This all means, instead of be passing down the store explicitly via props, we'll be passing it in implicitly via context.

Note that context works even on stateless components.

This is what an implementation of Provider would look like. It's indeed a pretty simple component.

export class Provider extends React.Component {
	getChildContext() {
		return {
			store: this.props.store
		};
	}

	render() {
		return this.props.children;
	}
}

Provider.childContextTypes = {
	store: React.PropTypes.object.isRequired
};

The object returned by getChildContext defines what all children components (no matter how deep they are down the tree) will get via context. In this case, the only property we are sending over is the store.

There's a condition for this to work, though. In React, the context is opt-in, meaning you need to somehow subscribe to it in order to gain access. This is how you do it:

class ChildComponent extends React.Component { ... }

ChildComponent.contextTypes = {
  store: React.PropTypes.object.isRequired
};

Generating container components with `connect`

The purpose of connect is to return a container component which is connected to the store: it injects part of the Redux state and also actions into our components as props, and it's also part of the react-redux library.

connect is a curried function: its first application returns a HOC (higher-order component). When we pass in our own component to this HOC, we are gonna have it turned into a container component connected to the Redux store.

Here's a rough, simplified implementation of connect:

export function connect(mapStateToProps, mapDispatchToProps) {
	return function (WrappedComponent) {
		class ConnectedWrappedComponent extends React.Component {
			componentDidMount() {
				const { subscribe } = this.context.store;
				this.unsubscribe = subscribe(this.handleChange.bind(this));
			}

			componentWillUnmount() {
				this.unsubscribe();
			}

			handleChange() {
				this.forceUpdate();
			}

			render() {
				const { getState, dispatch } = this.context.store;

				return (
					<WrappedComponent
						{...this.props}
						{...mapStateToProps(getState(), this.props)}
						{...mapDispatchToProps(dispatch, this.props)}
					/>
				);
			}
		}

		ConnectedWrappedComponent.contextTypes = {
			store: React.PropTypes.object.isRequired
		};

		return ConnectedWrappedComponent;
	};
}

Some notes on this implementation:

this.forceUpdate() makes the component re-render itself whenever the state tree changes. As noted here on the React docs, forceUpdate is a (discouraged) way to manually trigger the render method on a component.
We're well aware that the store's subscribe method returns an unsubscribe function. Here we are subscribing to the store changes on componentDidMount and unregistering our component from the list of listeners whenever the component gets unmounted (that is, within the componentWillUnmount lifecycle method).
The HOC renders our component with its own props plus all of the additional props calculated from the Redux store: data and callbacks.

`mapStateToProps` and `mapDispatchToProps`

connect returns a container component whose props will be the result of merging the objects returned from mapStateToProps and mapDispatchToProps together with its own props.

mapStateToProps is a function that receives store.getState() (that is, the global state) as a param and returns a configuration object used to map the Redux state tree into props our component will receive. The main idea behind mapStateToProps is to isolate which parts of the overall state this component needs.
mapDispatchToProps is also a function that receives store.dispatch as an argument and returns a configuration object used to determine which callback prop dispatches which Redux action.

Here's a simple example to make sense of these two functions:

function mapStateToProps(state) {
  return {
    count: state.counter
  };
}

function mapDispatchToProps(dispatch) {
  return {
    increment: dispatch({ type: 'INCREMENT' }),
    decrement: dispatch({ type: 'DECREMENT' })
  };
}

export connect(mapStateToProps, mapDispatchToProps)(Counter);

This means our container component will have access to:

this.props.count
this.props.increment()
this.props.decrement()

along with its other own props.

By the way, both the mapStateToProps and matchDispatchToProps receive ownProps as their second argument, enabling you to do some sort of computation involving the Redux global state and your component's own props:

function mapStateToProps(state, ownProps) { ... }
function mapDispatchToProps(dispatch, ownProps) { ... }

Using `connect` to generate a container component which is not connected to the store

By passing in null as mapStateToProps we are telling connect not to subscribe to the store as we don't need access to the global state tree and therefore it's pointless and wasteful for us to get notified whenever the store updates.

const mapDispatchToProps = (dispatch) => ({ dispatch });
export default connect(null, mapDispatchToProps)(Counter);

In this example we are only passing in mapDispatchToProps as we might need to be able to dispatch actions from within our component. However, and since this is such a common pattern, the react-redux authors realised it would be nice to agree on this convention: if we do not pass in any params whatsoever to the connect function, it will result into a container component which is not subscribed to the store (i.e.: it won't re-render whenever the state tree changes) albeit receiving store.dispatch as a prop.

export default connect()(Counter);

This means the component will know how to trigger Redux actions using this.props.dispatch({ type: INCREMENT }). Note how this chunk of code is completely equivalent to the previous one.

Extracting action creators

There's one more thing we can do to make our containers look prettier. Instead of using this.props.dispatch within our components, we can resort to action creators to dispatch actions from the view layer.

Action creators are nothing other than functions returning an object. We still need to have access to store.dispatch in order to successfully dispatch those actions. We do this in mapDispatchToProps and action creators become part of this.props.

function mapDispatchToProps(dispatch) {
	return {
		increment: () => dispatch(increment()),
		decrement: () => dispatch(decrement())
	};
}

where increment and decrement can live within another file, and are defined as follows:

export const increment = () => ({
	type: "COUNTER/INCREMENT"
});

export const decrement = () => ({
	type: "COUNTER/DECREMENT"
});

We now have access to this.props.increment from within our component:

<button onClick={this.props.increment}>Increment</button>

which is indeed way more convenient than doing:

<button onClick={this.props.dispatch({ type: "INCREMENT" })}>Increment</button>

This allows for abstracting our components from action definitions.

Side note: read about bindActionCreators for an even better way to achieve this.

Credits

This post is heavily inspired by Dan Abramov's Egghead course. I've also borrowed a couple images from this CSS Tricks post by Brad Westfall.

Making sense out of context

2016-12-30T00:00:00Z

The this keyword is probably one of the most misunderstood aspects of JavaScript. At the root of it for me, it allows us to reuse functions within different contexts, or in other words, it allows us to decide which objects should be focal when invoking a function.

Whenever you're trying to figure out what the value of this is, you need to look at where the function is being invoked. Not when it was defined, but specifically when it was called.

Let's say we have a function called sayHi which takes in a name and logs to the console Hi, ${name}, name being whatever argument name we pass in.

function sayHi(name) {
	console.log("Hello, my name is " + name);
}

If I were to ask you right now what name this last function is logging to the console, you wouldn't have a clue because you can't possibly know what name is until the function is invoked.

The exact same idea holds for the this keyword. We can't know what the value of this is until that function gets run.

Context Bindings

There are four different types of bindings in JavaScript:

Implicit Binding
Explicit Binding
new Binding
window Binding

Implicit Binding

TL;DR: look at the immediate left of the dot at call time.

Whenever you call a function that's attached to an object, look to the left of the dot, and that is what the this keyword is going to be.

var Person = function (name) {
	return {
		name: name,
		sayHi: function () {
			console.log("Hi, my name is " + this.name);
		}
	};
};

var homer = new Person("Homer Simpson");

homer.sayHi(); // "Hi, my name is Homer Simpson"

Now, what if we had a nested object within this homer object called daughter which also had a name property and a sayHi method?

var homer = {
	name: "Homer Simpson",
	sayHi: function () {
		console.log("Hi, my name is " + this.name);
	},
	daughter: {
		name: "Lisa Simpson",
		sayName: function () {
			console.log("Hi, my name is " + this.name);
		}
	}
};

homer.sayHi(); // Hi, my name is Homer Simpson
homer.daughter.sayHi(); // Hi, my name is Lisa Simpson

Well, this doesn't really matter as we always look at what's to the left of the dot, in this case, homer.daughter.sayHi() is going to be bound to the daughter object. The object which is immediately to the left to the dot is always the context used.

Explicit Binding

TL;DR: we explicitly tell a function what the context (= value of the this keyword) is by using one of these prototype methods: call, apply or bind.

This is about explicitly setting the value of this to a function upon execution.

Let's say we have a getCountryDetails function which is not a method on any object we've created, rather a function attached to the global scope:

function getCountryDetails() {
	console.log(
		this.country +
			"'s capital city is " +
			this.capital +
			" and as of " +
			arguments[0] +
			" the country has a population of " +
			this.population +
			" according to " +
			arguments[1]
	);
}

Note that getCountryDetails looks like a free flowing function, but there are actually no free flowing functions in JavaScript. They're all attached to some object. In this case, getCountryDetails is attached to the global window object.

Now, what we want to do is somehow call this function in the context of these two countries:

var au = {
	country: "Australia",
	capital: "Canberra",
	population: "23M"
};
var nz = {
	country: "New Zealand",
	capital: "Wellington",
	population: "4M"
};
var today = "30/12/2016";
var source = "Wikipedia";

We've got a number of ways to achieve this.

Function.prototype.call
Function.prototype.apply
Function.prototype.bind

What this means is every function (that is, every instance of Function) has a .call method, an .apply method and a .bind method that allows us to do what we want to do.

i. Call

Here's the signature for call:

fun.call(thisArg[, arg1[, arg2[, ...]]])

In layman's terms this means:

The very first argument call takes in is the context you want to use.
Afterwards, you can pass in any number of comma-separated values which will be treated as arguments for the function fun.

You can remember this because: call starts with "c" as in "comma-separated arguments" 💥

Here's our country details example using call:

getCountryDetails.call(nz, today, source);
// "New Zealand's capital city is Wellington and as of 30/12/2016 the country has a population of 4M according to Wikipedia"

ii. Apply

The signature for apply is as follows:

fun.apply(thisArg, [argsArray]);

As opposed to the call method, this one takes only two arguments:

First argument is the context we want to use.
Second argument is an array of values which are gonna be used as the arguments passed in to the function fun.

You can remember this because: apply starts with "a" as in "array of arguments" 💥

Again, here's our country details example using apply:

getCountryDetails.apply(au, [today, source]);
// "Australia's capital city is Canberra and as of 30/12/2016 the country has a population of 23M according to Wikipedia"

iii. Bind

bind is almost the exact same thing as call, except it defers the function invocation, i.e.: bind returns a whole new function instead of invoking the original one.

This new function is bound to the scope we pass in and also keeps track of the comma-separated values we've provided as arguments.

var getAustraliaDetails = getCountryDetails.bind(au, today, source);
// nothing happens just yet...

getAustraliaDetails(); // we need to manually run the resulting function
// "Australia's capital city is Canberra and as of 30/12/2016 the country has a population of 23M according to Wikipedia"

If we were to recreate Function#bind, this is what it'd look like:

Function.prototype.bind = function (context) {
	var fn = this;
	var outerArgs = [].slice.call(arguments, 1);

	return function () {
		var innerArgs = [].slice.call(arguments, 0);
		fn.apply(context, [].concat(outterArgs, innerArgs));
	};
};

One more thing about bind. This is a simple example of a functional programming technique called partial application which allows the remaining arguments to be passed in when the new bound function is called:

var missingSource = getCountryDetails.bind(au, today);
var missingAllArgs = getCountryDetails.bind(au);

missingSource(source);
missingAllArgs(today, source);

Let's recap:

call, apply and bind they all allow us to explicitly set the value of this when calling a function.
call and apply both invoke the bound function immediately.
bind doesn't invoke the bound function immediately, rather returns a new function we can run later.
call and apply differ only in the format they take extra arguments in: use comma-separated values for call, and an array of values for apply.
bind takes extra arguments as comma-separated values, just as call does.

`new` Binding

TL;DR: whenever we've got a function invoked with the new operator, the this keyword here is bound to the new object being built by the function constructor.

Let's say we've got this Dog function constructor which takes in a name, a breed and a colour. By the way, we have capitalised the first letter to express that this is function constructor, meaning it should be instantiated (i.e.: called with the new operator).

var Dog = function (name, breed, color) {
	// this = {} --> `this` equals to a brand new object
	// being created by the `new` operator whenever the
	// function gets instantiated.
	this.name = name;
	this.breed = breed;
	this.color = color;
	this.sayHi = function () {
		console.log("My name is " + this.name + ", woof!");
	};
};

Let's now instantiate a puppy:

var puppy = new Animal("Rufus", "German Shepherd", "Black");
puppy.sayHi();

As we're invoking the function constructor with the new keyword, JavaScript is (under the hood) creating a new object for us and saving it as our this, thus generating a brand new context.

This means, whenever we are instantiating a function constructor, we don't need to worry about binding the new instance to any particular context as it already has its own.

Window Binding

TL;DR: if none of the other rules apply, then the this keyword defaults to the window object. This holds true as long as you are not in strict mode, otherwise this is undefined.

Let's go back to our sayHi function:

function sayHi() {
	console.log("Hi, my name is " + this.name);
}

What if we just tried to invoke sayHi without specifying any context? Here we're not using call/apply/bind, there's also nothing to the left of the dot, nor we are using the new operator.

sayHi(); // undefined

Well, in this case we'll just get undefined back, because what's happening here is if you run a function that uses the this keyword but it's not bound to anything else (that is, doesn't meet any of the previous binding rules), then this is going to automatically default to the window object.

As a result, if we add a name property to the global window object we'll no longer get undefined:

window.name = "Homer"; // could also be `var name = 'Homer';`
sayHi(); // we now get "Hi, my name is Homer"

What's interesting though, is that if we run this function in strict mode, we get an error because strict mode is smart enough to know this might not be what we want. It kind of says: "Hey, you probably don't want to do what you're doing. You might now want the this keyword to reference the window object, so I won't let you do that".

function sayAge() {
	"use strict";
	console.log(this.age);
}

sayAge(); // bummer! type error thrown

ES6 Goodness: Arrow Functions

Arrow functions are automatically bound to their lexical scope, i.e.: this gets passed in from the parent into the arrow function.

function () {
    this.greeting = "G'day!";

    // If we don't bind this function, it'll echo out `undefined`
    setTimeout(function () {
        console.log(this.greeting);
    }.bind(this));

    // Binding here happens automagically using the parent scope
    setTimeout(() => {
        console.log(this.greeting);
    });
}

Some credits: I've first seen the terms implicit/explicit/new/window binding on this Egghead lesson by Tyler McGinnis.

Manipulating event streams in Bacon.js

2016-12-27T00:00:00Z

Being able to easily transform the values in observables is what makes functional reactive programming such a powerful tool. At the same time, one of the main goals of libraries such as Bacon.js and RxJS is to provide a unified programming model to handle any type of data, whether it's synchronous (an array) or asynchronous (an event stream).

These libraries make use of a simple, familiar API based on the functional programming extensions added to JavaScript arrays (known as the Array#extras). You are probably already familiar with the Array.prototype.map, Array.prototype.filter and Array.prototype.reduce methods JavaScript provides. map, filter and reduce work in pretty much the same way on observables as they do on collections.

Immutability

This is also where immutability comes into play. When mapping or filtering an instance of Observable you will get a whole new Observable instead of modifying the source one. This holds true for all the combinators in Bacon.js as well. In most cases, the new Observable will emit the transformed value whenever the source one emits a value.

Map

It's likely you've used Array.prototype.map() at some point, here's a quick example that maps all values in our array to their double:

const numbers = [1, 2, 3];
const doubles = numbers.map((number) => 2 * number);

Here, map receives a callback we call the transform function.

observable.map(f) works in exactly the same way: it maps all values that get pushed to our event stream using a transform function, and returns a new observable (immutability, remember?).

So, this would be kind of the same example but using event streams (where values get pushed asynchronously down the stream) instead of arrays (where values start off being in memory and the mapping happens in a synchronous way):

const numbersStream = Bacon.sequentially(300, [1, 2, 3]);
const doublesStream = numbersStream.map((value) => 2 * value);

Note that the resulting stream will end as soon as the source stream ends.

There are some neat built-in features around observable.map:

Instead of a transform function, you can also pass in a constant value:

const ones = clicks.map(1);

This means every value that gets pushed down the stream will be mapped to a constant, in this case, the number 1.

You can also use a "property extractor string" like .keyCode. This way, if the argument map receives is a string starting with a dot, the elements will be mapped to the corresponding field/function in the event value. For instance: map('.keyCode') will pluck the keyCode field from the event value. If keyCode was a function, the result stream would contain the values returned by the function.

Filter

observable.filter(f) filters out values using the given predicate function, just like Array.prototype.filter. This basically means we use the function passed in to determine whether the value should be emitted or skipped entirely:

if f(value) evaluates to true (or any truthy value), then value is emitted.
if f(value) evaluates to false (or any falsey value), then that particular value is skipped (meaning it doesn't get pushed down the stream).

The resulting stream will end along with the source stream.

In this example, we are only emitting those values greater than 20:

const numbersStream = Bacon.sequentially(300, [2, 30, 22, 5, 60, 1]);
const filteredStream = numbersStream.filter((value) => value > 20).log("filteredStream");

Note that, contrary to what happens with map, the filtered stream does not emit a value each time the source emits a value — after all that's the whole point of using filters.

Instead of passing in a function, you can also provide:

a constant value: true will include/emit all values, false will exclude/skip all of them (might be useful if you pass in a boolean variable, think of it as a switch):

observable.filter(false);

a property extractor string: let's say you have a boolean property you'd like to filter by, say isAvailable. In order to get only the available values, we just need to do:

productsStream.filter(".isAvailable");

an instance of Property: we can also pass in a property to filter out the values of the event stream based on the current value of the property. The stream will emit the value only if the property is truthy when the value gets pushed down the stream.

Fold or Reduce

Reducing roughly means deriving a value from all of the values in a list or collection. At the core of it, we get a single, computed value out of a bunch of other values.

Here's an example of how Array.prototype.reduce works:

const numbers = [1, 2, 3, 4, 5];
const sum = numbers.reduce((accumulator, value) => accumulator + value, 0);

Reduce works in exactly the same way with asynchronous values (ie: with event streams). We need to pass in:

Initial value (also called the seed value)
Accumulator function which takes an accumulator as the first argument and the current value as the second argument.

By the way, fold and reduce are aliases. You can use them interchangeably.

In this example we sum all of the numbers in the source stream. The resulting stream emits the result of the sum once the source stream is done emitting values.

const numbersStream = Bacon.sequentially(300, [1, 2, 3, 4, 5]);
const foldStream = numbersStream.fold(0, (accumulator, value) => accumulator + value).log("foldStream");

The resulting stream will emit only once after the source stream has ended, and it will also end afterwards.

Note that fold or reduce always return an instance of Property.

Scan

observable.scan(seed, f) works pretty much in the same way fold does, but for the number of values pushed down the resulting property. scan emits a value every single time a value is emitted by the source stream.

Once the last value gets pushed down the resulting property, it ends. This happens simultaneously with the termination of the source stream.

Here's kind of the same example we used for fold. The only difference is the resulting stream here will emit on each and every partial result — that is, whenever the accumulator function runs.

const numbersStream = Bacon.sequentially(300, [1, 2, 3, 4, 5]);
const scanStream = numbersStream.scan(0, (accumulator, value) => accumulator + value).log("scanStream");

Note that scan also returns an instance of Property.

Take

observable.take(n) takes the first n values from the source stream. Once the first n values have been emitted, the stream ends.

Two common edge cases are:

If the source stream emits less than n values, both streams will emit the same number of values and end at the same time.
If n <= 0 this is equivalent to Bacon.never(), that is, it will immediately end.

const numbersStream = Bacon.sequentially(300, [1, 2, 3, 4]);

// This will emit the first two values and end
const takeStream = numbersStream.take(2).log("takeStream");

// This will immediately end
const takeNoneStream = numbersStream
	.take(0) // might as well be a negative number
	.log("takeNone");

// This will emit the first 4 values of the source stream and end
const takeMoreThanFourStream = numbersStream.take(20).log("takeMoreThanFourStream");

Side note re: filter vs take. If we were working with arrays, we could easily accomplish what take does by doing:

const numbers = [1, 2, 3, 4];
const takeFirstThree = numbers.filter((value, index) => index <= 2);

The key here is the index argument which gets automatically passed in to the predicate function. This is not the case with the bacon-y version of filter. Since no index gets passed in (events occur in an async fashion), we need this resort to the take operator to achieve this.

Skip

observable.skip(n) skips the first n values from the stream, and emits all values thereafter. It will end once the source stream ends.

Again, we've got a couple of edge cases here:

If n is greater than the number of events the source stream emits before ending, then the resulting stream will end but only after all events in the source stream have been emitted.
If n <= 0 it will emit all of the values in the source stream and then end, that is, it has no effect whatsoever.

const numbersStream = Bacon.sequentially(100, [1, 2, 3, 4]);

// This will skip the first two values and then end
const skipStream = numbersStream.skip(2).log("skipStream");

const skipNone = numbersStream
	.skip(0) // might as well be a negative number
	.log("skipNoneStream");

// Will end but not immediately,
// rather after the source stream has emitted all of its four values
const skipMoreThanFourStream = numbersStream.skip(20).log("skipMoreThanFourStream");

First

observable.first() emits only the very first value in the source stream. This is essentially the same as observable.take(1).

If the source stream ends without emitting a value, the new stream will immediately end, being equivalent to Bacon.never().

const numbersStream = Bacon.sequentially(100, [1, 2, 3, 4]);
const firstValueStream = Bacon.first().log("firstValueStream");

Last

observable.last() emits only the last value from the source stream and then ends.

If the source stream is empty and immediately ends, the resulting stream will be immediately terminated as well.

const numbersStream = Bacon.sequentially(100, [1, 2, 3, 4]);
const lastValueStream = Bacon.last().log("lastValueStream");

Take While

observable.takeWhile(f) emits all values as long as the predicate function f applied to the current event returns true (or a truthy value). The stream will terminate (stop emitting) as soon as the predicate function evaluates to false (or, you guessed it, any falsey value).

If no predicate function is provided, the identity function will be used, ie: (x) => x.

const numbersStream = Bacon.sequentially(300, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
const takeWhileStream = numbersStream.takeWhile((value) => value * value < 30).log("takeWhileStream");

Take Until

observable.takeUntil(otherStream) takes elements from the source event stream until an event (any event) gets pushed down the stream passed in as a param, and then ends.

If otherStream ends without emitting any values, it is ignored (that is, all values in the source stream gets emitted in the result stream as well, meaning the operator has no effect at all).

In this code example below the result stream will emit all first five values — this is because the second stream gets its first value emitted 1.5 secs after being subscribed to, while the source stream is capable of emitting five values in that period as it emits every 300 milliseconds.

const numbersStream = Bacon.sequentially(300, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
const zerosStream = Bacon.sequentially(1500, [0, 0]);

// Take values from the numbers stream until
// an event gets pushed down the zeros stream
const takeUntilStream = numbersStream.takeUntil(zerosStream).log("takeUntilStream");

// Bacon.never() emits no values.
// However, takeUntilNever emits all values in the source stream
const takeUntilNeverStream = numbersStream.takeUntil(Bacon.never()).log("takeUntilNeverStream");

Delay

observable.delay(wait) will return an event stream that emits all values in the source stream but after wait milliseconds. Note that we are not delaying every single value, rather this is a pause before the resulting stream starts emitting.

If the provided delay is zero or a negative value, the resulting stream will emit at the same rate the source stream does.

One more thing. Note that this operator will not delay the initial value of a property. This means, if you delay a property, you will get the initial value emitted immediately, and all subsequent values emitted appropriately after wait milliseconds.

const numbersStream = Bacon.sequentially(300, [1, 2, 3]);
const delayStream = numbersStream.delay(900).log("delayStream");
const noDelayStream = numbersStream
	.delay(0) // could also be a negative number
	.log("noDelayStream");

Debounce

Debouncing is not a Bacon specific concept. You've probably come across Lodash's debounce before. The debounce technique allows us to group a sudden burst of sequential events (keystrokes, for instance) into a single one. It basically limits the rate at which a function or event can fire. Here's an interesting article on debouncing with some useful examples.

In the same way, what observable.debounce(delay) does is to delay emitting a value in the resulting stream until after delay milliseconds have elapsed since the last time the source stream has emitted. That is, it creates a new debounced version of the original observable which will emit a value only after a delay milliseconds period of no events.

Which event gets emitted after that sec? The last one.

Consider this example in which we've got a button you can click as many consecutive times as you want. Every time you click on the button, an event will get pushed down clicksStream. However, we derive a new debouncedStream from this one that emits only a second after the last time you've clicked on the button, provided it has remained unclicked for that whole second.

const button = document.getElementById("btn");
const clicksStream = Bacon.fromEvent(button, "click").map("This is a click event");
const debouncedStream = clicksStream.debounce(1000).log("debouncedStream");

This marble diagram might help visualise the whole idea behind debounce:

Debounce is particularly useful for implementing behaviour that should only happen after the input has stopped arriving. Probably the most traditional example is building a typeahead search component that triggers an API call whenever we type on an text input field. However, we don't want to hit the API on every keystroke as that'd be expensive in terms of performance. What we do instead is to wait until the user has finished typing.

const inputStream = Bacon.fromEvent(document.querySelector("#input"), "keydown")
	.debounce(300) // limit the rate of queries
	.map((event) => event.target.value); // get text value from event

In this example what we do is to wait until there has been no further input for the last 300 ms. — we assume the user has then finished typing, and we fire the Ajax call.

Debounce Immediate

Debounce implementations such as Lodash's one take an optional argument called leading — although here in Baconland we call it immediate.

An immediate debounce fires the event on the leading edge (the very beginning of the wait interval) instead of the trailing edge (the end of the wait interval). This is useful in circumstances like preventing accidental double-clicks on a submit button from firing a second time.

Throttle

observable.throttle(delay) returns a new throttled version of the original observable, which will emit values at most once every delay milliseconds only. By using throttle we prevent our stream from firing events more than once in that wait period. Here's a great way to visualise how debounce and throttle work.

A traditional example is infinite scrolling: you need to check how far the user is from the bottom of the page, because if they are close to the end (whatever we decide close is) we need to request more content via Ajax and append it to the page. debounce wouldn't be of much help here as it'd only trigger when the user stops scrolling. throttle, on the other hand, will work a charm in this case.

Not

observable.not() will result in a new stream where all values are inverted, that is, all truthy values will be mapped to false, whereas all falsey values will be mapped to true.

The resulting stream will end simultaneously with the source stream.

const booleansStream = Bacon.sequentially(300, [true, false, true]);
const invertedBooleansStream = booleansStream.not().log("invertedBooleansStream");

The not operator will work just fine even if the values on the source stream are not booleans:

const booleansStream = Bacon.sequentially(300, ["bacon", 1, 0, null, "", {}, []]);

The example above returns false, false, true, true, true, false, false.

Note that using the .not() operator is equivalent to using the map operator in this way: .map((value) => !value)).

Making infinite streams end

Some of these operators (take, skip, first, last, takeWhile, takeUntil) have the ability to turn an infinite stream into a finite one. This means that the resulting stream will end at some point, ie: will emit a complete signal.

Visualisation tools

Here's a couple of neat tools that will help you visualise many of the different ways to manipulate and combine streams. Even though most of these are RxJS specific, concepts behind operators are certainly similar between libraries.

Event streams vs Properties in Bacon.js

2016-09-21T00:00:00Z

In Bacon.js we operate with two different types of observable data types: Event Streams and Properties. Here's a brief explanation of what these concepts are along with some concrete examples to illustrate when to choose one over the other.

Event streams represent discrete values over time

You can think of event streams as lists of events happening over time.

[(t1, v1), (t2, v2), ..., (tn, vn), ...]

Examples of event streams are:

Mouse clicks on a button:

const clickStream = Bacon.fromEvent(document.querySelector("#button"), "click");

Keystrokes on an input field:

const keyStream = Bacon.fromEvent(document.querySelector("#input"), "keyup");

A promise that resolves after hitting an API and coming back with data:

const ajaxCall = axios.get("//your.api.com/endpoint");
const dataStream = Bacon.fromPromise(ajaxCall);

Note that for these examples, talking about an initial value wouldn't make any sense. Also, these streams will only happen to have a value (ie: event) pushed down the stream when the user either clicks on the button or presses a key on the input field, or when we hear back from the API. Remember that clicking on the button means pushing that click event onto the stream: our value is the click event itself.

Properties introduce the notion of continuous values

Properties represent values that change over time. The value of a property changes in response to events, which means that any stream may be easily converted into a property.

In most ways properties behave very much like event streams. The main differences between the two are:

Properties can have an initial value. They don't always do, though: depending on how a property is created, it may or may not have one.
Properties remember or hold the last value they've received. This means properties are continuous, as opposed to event streams which are discrete. The only exception to this rule is when a property doesn't get assigned an initial value when it gets created.
The current value stays as its last value even after the stream has ended.

Examples of properties are:

The position of our mouse cursor determined by any series of movements:

const mouseProperty = Bacon.fromEvent(document, "mousemove")
	.map((event) => `(${event.x}, ${event.y})`)
	.toProperty();

The value of an input field at any given time:

const inputProperty = Bacon.fromEvent(document.querySelector("#input"), "keyup")
	.map(".currentTarget.value")
	.toProperty("This is the default value");

The Observable interface

Both streams and properties implement the Observable interface, meaning they share a lot of methods: onValue, onError, fromPromise, map, among many others. Check out the full list of shared methods here.

These methods typically return another observable to allow for further chaining. Of course, there are exceptions (such as onValue).

Assigning values to DOM elements (or how to purposely create side effects)

This concept of "current value" makes properties great for assigning values and attributes to DOM elements. Bacon provides a helper method for assigning the value of a property to a DOM node:

property.assign(nodeElement, setterMethod [, ...args])

This calls the method setterMethod of the given nodeElement whenever the value of the property changes (even for the initial value!). You can optionally provide arguments which will get passed in onto the setter method.

So, if you want to hide or show a button based on the value of a property, you could do something along the lines of:

buttonVisibilityProperty.assign($("#my-button"), "toggle");

Here the value of the property gets automagically passed in onto toggle(). Also, we assume we are dealing with a boolean property here.

Now, chances are most of us aren't using jQuery in our projects. How can we make assign() work with our vanilla JS DOM manipulation skills?

DOM nodes, when not wrapped in the jQuery object, don't have setter methods like attr(), html() or text(). That's why assign isn't quite the best option out there if we don't use jQuery.

Probably an example will help see this better: let's say we extend our HTMLInputElement prototype, which is sort of what jQuery does (this is bad though! don't do it, my intent is just to showcase why we can't usually resort to assign() for updating the DOM without jQuery):

HTMLInputElement.prototype.setValue = function (message, value) {
	this.value = value;
	console.log("clicked", message);
};

Bacon.fromEvent(document.querySelector("#button"), "click")
	.map(1)
	.scan(0, (accumulator, value) => accumulator + value)
	.assign(document.querySelector("#input"), "setValue", "rawr");

We can even pass in a third argument. If we do, those arguments we pass in are gonna come first than the property value. See how on the prototype method message comes before the actual value? So, what do we do if we want to mutate the DOM state based on the value of a property but can't use assign()? Well, assign is nothing more than a fancy version of onValue(). We could do the following:

const button = document.querySelector("#button");
const input = document.querySelector("#input");

Bacon.fromEvent(button, "click")
	.map(1)
	.scan(0, (accumulator, value) => accumulator + value)
	.onValue((count) => (input.value = count));

Note we can use assign() only with properties, but we can use onValue() in this way with event streams as well.

Creating properties from event streams

There are a couple methods you can use to turn your event stream into a property:

stream.toProperty(initialValue) creates a property based on the event stream. Passing in an initial value is optional. If we don't provide one, the property will get its first value from the stream, and will always hold a value thereafter. Here's a super simple example that logs out the current timestamp for every click on a button:

const counter = Bacon.fromEvent(document.querySelector("#button"), "click")
	.map(() => Date.now())
	.toProperty("initial value")
	.onValue((value) => {
		console.log(value);
	});

Just out of curiosity, have a go at what happens if you replace () => Date.now() within map() with just Date.now().

We can also scan() and fold() event streams to convert them into properties. These are similar to reduce() in functional programming — think of Array.prototype.reduce(). An example of scan() is the counter we built before when we went through how assign() works.

Note that fold() is a little bit different from scan(). Consider this example:

Bacon.fromArray([1, 2, 3, 4])
	.scan(0, (accumulator, value) => accumulator + value)
	.onValue((value) => {
		console.log(value);
	});

We will get all intermediate values logged out to the console: 0, 1, 3, 6 and 10. That is, the property updates for every single calculation.

Bacon.fromArray([1, 2, 3, 4])
	.fold(0, (accumulator, value) => accumulator + value)
	.onValue((value) => {
		console.log(value);
	});

fold(), on the other hand, will only emit a value and log to the console after going through all of the elements in the array (ie: will only log out the final value to the console, which is 10).

One more thing: reduce() and fold() are aliases.

Adding an initial value after a property has been created

property.startWith(value) allows you to add an initial value to a property later in time. If the property has already an initial value of its own, it will be overwritten.

This is particularly useful when you receive a property from somewhere else and you have no control over how that property gets created. You can then add an initial value before subscribing to it.

Going the other way around: creating event streams from properties

When you have a property, you might want to turn it back into an event stream. Again, there are a couple ways to achieve this:

Probably the easiest way is to use the changes() method, which creates an event stream that emits every time the value of our property changes. The only gotcha here is that this doesn't include the initial value of the property.
Bacon offers another method called toEventStream() which behaves in exactly the same way than changes(), except that it includes the property's initial value.
Another option is polling the property at fixed intervals by using sample(interval). This basically creates an event stream that emits the value of the property at every given interval.
There's yet another alternative, which involves using the sampledBy(EventStream) method. What this one does is sample the property every time the event stream passed in as an argument emits a value.

Subscribing to properties

The process of subscribing to both types of observables is the same: you call the onValue() method and pass in a callback function. But when you subscribe to a property which has a current value, the callback will be executed immediately (synchronously) with the current value of the property.

const property = Bacon.fromEvent(document.querySelector("#button"), "click")
	.map("clicked")
	.toProperty("this is the initial value")
	.onValue((value) => {
		console.log(value);
	});

This example will log "this is the initial value" before you first click on the button.

Just out of curiosity (again), have a look at what would happen if you map the stream value right after turning it into a property — in other words, just call toProperty() before map().

Wrapping things in Bacon

2016-09-17T00:00:00Z

And by wrapping things in Bacon I mean creating observables by wrapping values as reactive data types in Bacon.js. I believe this is a good starting point if you are interested in functional reactive programming.

A little bit of context

Functional Reactive Programming (FRP) is functional programming with first class representation for values that change over time. We can represent sequences of any event occurring asynchronously at unknown points in time as a stream.

There are many implementations of the core concepts of FRP, but today we'll be using Bacon.js.

In Baconland we have two different abstractions for reactive data: Properties and Event Streams. Properties are continuous values whereas event streams are discrete values. More on this later.

Creating Observables

We use observables to wrap any chunk of data (numbers, strings, arrays, objects, collections, DOM events like button clicks or key presses) and decorate it with stream-like qualities.

You can create reactive datatypes by wrapping these various sources. Which wrapper to use depends on what kind of data source you have. Let's have a look at the most common ones.

A little aside: since streams are immutable by nature we can safely use the ES6 const keyword to declare our variables, to convey that reassignment is off the table.

One more thing: the reason why we need to create an instance of a Bacon-y data type is that JavaScript doesn't implement FRP natively (yet?), so in order to get these observable objects with all the built-in reactive superpowers we need to wrap data sources in a handful of constructor methods Bacon provides. For instance, mouse clicks is a valid source for an event stream.

Finally, check out the official docs for a more thorough reference of wrapper methods and further examples on how to create reactive datatypes from other sources. You can also play around with this CodeSandbox as you follow along these examples.

From a DOM event using `Bacon.fromEvent`

We can use observables to interact with the DOM. By using Bacon.fromEvent we can listen for any DOM events like mouse clicks, key presses, input changes, page scrolls, mouse moves, etc.

For instance, this event listener and handler:

const button = document.querySelector("#btn");

button.addEventListener("click", () => {
	console.log("you just clicked on the button");
});

can be baconified by doing:

Bacon.fromEvent(document.querySelector("#btn"), "click").onValue(() => {
	console.log("you just clicked on the button");
});

Not a big difference so far, but Bacon provides a functional interface to manipulate, combine and handle event streams:

const button = document.querySelector("#btn");
const clickStream = Bacon.fromEvent(button, "click");

clickStream
	.map(() => Math.round(10 * Math.random()))
	.filter((value) => value > 0)
	.onValue((value) => {
		console.log(value);
	});

clickStream
	.skip(1)
	.take(4)
	.onValue(() => {
		console.log("this displays on clicks 2-5 only");
	});

Now try to rewrite that using callbacks...

From a promise using `Bacon.fromPromise`

A stream from a promise will resolve the promise only when subscribed to, and then push the resolved value into the stream. This stream will contain a single value or an error, followed immediately by stream end.

const ajaxCall = fetch("https://files.fedknu.com/blog/wrapping-things-in-bacon/cities.json")
	.then((response) => response.json())
	.catch((error) => {
		console.error("parsing failed", error);
	});

Bacon.fromPromise(ajaxCall)
	.flatMap(Bacon.fromArray)
	.map((location) => `${location.city}, ${location.state}`)
	.onValue((location) => {
		console.log(location);
	});

From a timer using `Bacon.sequentially`

Bacon.sequentially(interval, values) takes an interval in milliseconds and an array of values, and creates an event stream that emits one value at a time, all delivered with the given interval. It will stop once all values have been emitted.

Bacon.sequentially(1000, [1, 2, 3, 4, 5]).onValue((value) => {
	console.log(value);
});

From a timer using `Bacon.repeatedly`

This one is sort of similar to Bacon.sequentially, except for this one never stops emitting values. Bacon.repeatedly(interval, values) repeats all the values indefinitely with the given interval in milliseconds.

Bacon.repeatedly(1000, ["spring", "summer", "autumn", "winter"]).onValue((value) => {
	console.log(value);
});

From a timer using `Bacon.interval`

Bacon.interval(interval, value) repeats the (single) value indefinitely with the given interval in milliseconds.

In this example, the stream will emit "beep!" every second. It's important to note this stream never ends once you subscribed to it unless you specifically unsubscribe.

Bacon.interval(1000, "beep!").onValue((value) => {
	console.log(value);
});

From a timer using `Bacon.later`

Bacon.later(delay, value) creates a single-element stream that produces the given value after the specified delay (also in milliseconds).

In this case, Bacon will throw the value "I am one second late" into the stream after one second:

Bacon.later(1000, "I am one second late").onValue((value) => {
	console.log(value);
});

From an array using `Bacon.fromArray`

Bacon.fromArray(values) returns a stream that fires one event for each element in the array to the first subscriber only. The stream ends after these values have been delivered.

Bacon.fromArray([1, 2, 3, 4])
	.reduce(0, (accumulator, value) => accumulator + value)
	.onValue((value) => {
		console.log(value);
	});

By the way: fold() and reduce() are aliases. You can use them interchangeably.

One more thing: try replacing reduce() with scan() to see what happens.

From a single value using `Bacon.once`

Bacon.once(value) creates an event stream that delivers the given single value for the first subscriber only (in other words, this means this stream can only have one subscriber). The stream will end immediately.

Bacon.once("rawr").onValue((value) => {
	console.log(value);
});

From a callback using `Bacon.fromCallback`

Bacon.fromCallback(sink) creates a stream from a function that accepts a callback (aka: sink). The function is supposed to call its callback just once.

In this example, we are creating a stream that outputs a single value and ends after that. Here sink is the callback, as in, the sinkhole you throw stuff into to make it go off and be an event in the event stream.

Bacon.fromCallback((sink) => {
	setTimeout(() => {
		sink("some-new-value-for-event");
	}, 1000);
}).onValue((value) => {
	console.log(value);
});

Or you can also:

sink(new Bacon.Error("Died..."));

From anything else using `Bacon.fromBinder`

If none of the methods above work for your particular use case, you can create your very own custom stream with Bacon.fromBinder(subscribe).

This factory function takes in a subscribe callback which looks like this:

const subscribe = (sink) => sink(event);

sink is another function that we can use to push events down the stream within our subscription function. These events can be either:

plain values, such as a string, a number, an instance of Date, etc.
single instances of the Event object, such as Bacon.Error (to wrap errors that need to travel down the stream) and Bacon.End (to indicate the stream has been terminated).
array of instances of the Event object (e.g. multiple Bacon.Error).

Here we'll be recreating the Bacon.interval example above:

const interval$ = (interval, value) =>
	Bacon.fromBinder((sink) => {
		const id = setInterval(() => sink(value), interval);

		return () => clearInterval(id);
	});

interval$(1000, "beep!").onValue((value) => {
	console.log(value);
});

Note that our subscribe function needs to return its own unsubscribe function. That's why, in this case, we are returning a reference to the global clearInterval function to prevent the interval from emitting any more values. This unsubscribe function should release and clean up all resources that the subscribe function reserved and used.

Using `Bacon.never`

Bacon.never() creates an event stream that:

will immediately end, and
will never produce/emit any events

Yeah, I know. Why would you ever want this? One particular use case would be using flatMap() along with Bacon.never() for converting and filtering values at the same time. In this example we are converting strings to integers while skipping empty values:

stream.flatMap((text) => (text != "" ? parseInt(text) : Bacon.never()));

So rather than returning an empty event (null or whatever) and then filter that out, we can just return a stream that'll never emit.

Subscribing to an Observable

Since all values happen over time, we have no idea when they will be available, thus we can't treat these values synchronously. We need to provide a callback that can be ran once a value gets pushed to the stream. This can be done with a subscriber, which is just a function that is called once you have data coming through in your observable.

In Bacon.js we usually use the onValue() method to subscribe to an observable.

Heads up #1: onValue returns a function to unsubscribe from the stream. This is important to remember as it means that we cannot continue our chaining pipeline after a subscriber method. More on this later.
Heads up #2: All reactive datatypes created using Bacon.js are lazy evaluated. This means the data flow just won't happen at all unless you have a subscriber at the end of your pipeline. This also means event listeners aren't bound to the DOM before the first subscription.

There is also a special subscriber that behaves a bit differently: log(), which we can use for logging all of the values in an observable. This logger method will initiate the data flow, but it won't return an unsubscribe function, rather the observable itself which means we can keep on chaining methods.

Unsubscribing from an Observable

When you register a subscriber to a stream (that is, whenever you chain the onValue() method to your stream) you get back an unsubscribe function which you can call later on to unsubscribe from that stream.

const unsubscribe = Bacon.fromEvent(document.querySelector("#btn"), "click").onValue(() => {
	console.log("you just clicked on the button");
});

// later on...
unsubscribe();

Unsubscribing simply means to stop listening for events (or, in other words, destroying the stream). This will also properly clean up and dispose of any event handlers and temporary objects created.

Now, if this was the last of the subscribers (in this case it was the only one) and you run the unsubscribe function, the stream gets closed, ie: the event handler will be removed from the DOM. Useful links

Some resources I've used to put this post together:

https://github.com/baconjs/bacon.js/
https://github.com/darrennolan/bacon.js-docs/
https://github.com/mikaelbr/bacon-love/

Web frontend resources

2016-08-03T00:00:00Z

This is a list of curated resources on frontend developement I think are worth having a look at.

F. Knüssel

Configuring and using Sublime Text in 2026

1) Package control

2) Core packages

3) TypeScript support

4) LSP settings

5) Project file

6) Solving the Node.js PATH problem

7) Opening a project from the terminal

8) User settings

9) Using Copilot via LSP-copilot

10) Wishlist

A self study roadmap for engineers transitioning to pure maths

Prerequisites

1) Learn proof writing

2) Real analysis

3) Abstract algebra

4) Linear algebra

Recommended books

How to block distracting sites on Mac

Building a mental model of the Elm Architecture (for React developers)

The main concepts

Messages

Model

Update

View

Commands and subscriptions

How it compares to MVC

How it compares to Flux

How it compares to React

An example

App defaults

Trading complexity for simplicity with 11ty

Choosing between links and buttons

Semantics

State

Tab order

Interactions

Rotor and Quick Keys

Building your own accessible button

Configuring Sublime Text to work with Prettier and ESLint

Enable the subl command line tool

Install JsPrettier

Install SublimeLinter and SublimeLinter-eslint

Install ESLint-Formatter

Web frontend devtools

General

Web APIs and browser compatibility

CSS

Regex

Accessibility

Screen readers

Screen reader plugins

VSCode extensions

Chrome extensions

Bookmarklets

Apps

Useful webapps/websites

Browser-based devtools

Jira search engine in your browser

Code reviewing checklist

Coding style, conventions and standards

Complexity, readability and maintainability

Architectural overview

Automated testing

Accessibility

Internationalisation

Security

Performance

Cross browser/platform compatibility

Operational maturity and production readiness

Functional review

Focusing and skipping tests

Mocha

Jasmine

Fixing keyboard navigation for MacOS browsers

Fixing Firefox

Fixing Safari

Chrome should work fine out of the box

Testing asynchronous code

Enable the `subl` command line tool

Adding multiple `window.{onload, onerror}` events

Re-implementing Lodash's `get` method

A synchronous `Observable` example: `Rx.Observable.from`

An asynchronous `Observable` example: `Rx.Observable.interval`

Observing (asynchronous) DOM Events: `Rx.Observable.fromEvent`

The `Node` interface

The `window` object

The `location` object

The `history` object

The `navigator` object