sglavoie.com – Category: Tools

First Steps with RxJS

Sébastien Lavoie — Sun, 01 Oct 2023 19:45:00 -0600

Introduction

While building an Excel add-in, I came across the need for a more reactive style of programming due to the asynchronous nature of the APIs and the unpredictability of some events occurring in the spreadsheet. RxJS is one of those frameworks that can help with that. It’s a library for composing asynchronous and event-based programs by using observable sequences. It provides a set of operators to transform and combine streams of data. It’s a powerful tool that can be used to manage complex flows of data in a declarative fashion. It’s also a bit of a beast to learn, so I thought I’d share some of my notes and learnings along the way.

We’ll first go over some basic concepts and terminology, move on to an attempt at depicting those various concepts, present common operators, touch upon reactive testing and then cover some tips and tricks.

Basic concepts

This is a push-based approach as opposed to a more common pull-based approach.
The Observer design pattern is implemented.
Observables are the producers of a stream (the Subject) that you can subscribe (listen) to.
- They are “cold” by default, meaning they don’t emit values until they are subscribed to.
- They can deliver values synchronously and asynchronously.
- They can be cancelled by unsubscribing.
Observers are the consumers of data produced by observables. They “subscribe” via a subscription to the stream of events emitted by the observable.
- They execute some code when a new value is received.
- They implement next, error and/or complete.
- The next method is called whenever a new value is emitted.
- The error method is called whenever an error occurs with an emission from the observable.
- The complete method is called whenever the observable is done, i.e. when no more values will be emitted from the stream in the future.
- By default, this leads to unicasting, where a single subscription gets values from the producer.
In the context of an Excel spreadsheet, we could think of the values from cells A1 and B1 as the producers of a stream of values that can be subscribed to by a cell C1 – the consumer – to perform some calculations based on the values from A1 and B1 which could be updated over time (i.e., emitting new values in the stream of data).

In an imperative programming paradigm, we would write code that executes a series of steps to produce a result. In a reactive programming paradigm, we would write code that reacts to events as they occur. Here’s a simple example to illustrate this:

 typescript
 
 
 
// Imperative approach
let a = 2;
let b = 3;
let c = a + b;
console.log(c); // 5

a = a + 1;
console.log(c); // 5: `a` was updated but `c` was not

c = a + b;
console.log(c); // 6: `c` was updated after `a` was updated

b = 5;
c = a + b;
console.log(c); // 8: `c` was updated after `b` was updated


// Reactive approach
import { Subject, combineLatest, map } from "rxjs";
const a$ = new Subject();
const b$ = new Subject();
const c$ = combineLatest([a$, b$]).pipe(map(([a, b]) => a + b));
c$.subscribe((c) => console.log(c));
a$.next(3); // logs nothing because b$ has not emitted yet
b$.next(4); // logs 7 at this point (latest a + b)
a$.next(4); // logs 8 at this point (latest a + b)

Everything is a stream

What follows is a metaphorical drawing designed (as best as I could…) to help you understand the complex world of reactive programming with RxJS. It’s not a one-to-one mapping but aims to give a general feel of how things interconnect.

Think of reactive programming as managing a complex water supply system for a bustling town and a high-tech factory. Water from the glacier (Producer) flows as a river (Stream) through a landscape filled with dams, turbines, and filters (Operators).

Town residents and the factory subscribe to this river to fulfill their water needs. A subscription is like turning on a valve at the pumping station to let the water flow into your pipeline.

Meanwhile, the factory refines the water and feeds it back into the system, acting like a Subject in RxJS. Natural calamities (or dirty, unfiltered water) disrupting the flow signify errors, while the dam’s control room (Schedulers) regulates the rhythm of the entire system.

A simple drawing like that won’t do justice to the complexity of the RxJS ecosystem. Let’s nevertheless try to break down a bit more how concepts relate to each other.

The Producer (glacier) is the source of the stream. It can be a user action, a network request, a timer, etc. There can be multiple sources of data emitting different types of values. In this example, there is a tributary (a smaller river) that feeds into the main river. By merging the two streams, we can get a single stream of data from both sources.
- While it may be useful to merge different streams of data and transform them along the way, it is not necessary or always needed. In this drawing, the ReplaySubject merely captures raw data as it arrives from the river and makes it available to late subscribers.
The Stream is the flow of data. It can be a single value or a sequence of values over time. Here, it may represent the flow of data throughout the whole application, where different events (mouse click, keyboard, etc.) are emitted from different sources (or components) and may be consumed in a modified fashion (e.g., keeping a single property from an object, filtering out some values, etc.).
- Here, we have the town which subscribes to different streams that have been transformed already (electricity and water subscriptions). The town might be considered a Consumer of the stream and is the data that ends up being displayed in the UI or sent back to a server.
Operators are functions that transform the stream. They can be used to filter, combine, or modify the data.
- Our metaphor contains a couple of them. There’s a water turbine – representing a transformation operator – that transforms water into electricity (maybe it’s a mergeMap that creates a new observable and maps it to a different structure) or water filters – representing the filtering operators – that filter out unwanted particles (maybe it’s a filter that removes some values from the stream).
Subscriptions are the consumers of the stream. They can be used to listen to the stream and perform actions when new values are emitted.
- For instance, when the water bottling company receives water via its pipe, it may modify the stream by adding minerals to it (e.g., map operator) and then bottle it up to deliver water. This creates a dependency chain where the bottling company is a consumer of the stream and a producer of a new stream that can be consumed by the town.
- If we zoom in on the water bottling company section, we can see that the water delivery truck “subscribes” to the product of the company and will likely want to deliver a truckload of water bottles once it is full (e.g., buffer operator). If we look at the case where the truck delivers water with a giant container that happens to have a small leak, then we know that once the container starts filling with water, it will start leaking. This is akin to a hot observable where the stream starts emitting values immediately, even if there are no subscribers. We could say this is also a stream that uses the throttleTime operator to only emit values every 5 seconds, dropping a small amount of water in the process. Whether the container is nearly empty or full, it will still leak water every 5 seconds. This is different from a cold observable where the stream only starts emitting values once a subscriber is listening to it, such as when a well-functioning container is plugged into a destination to deliver water.
Subjects are both producers and consumers. They can be used to multicast values to multiple subscribers.
- The water purification factory consumes water from the stream: as such, it is an observer as it reacts to the input stream (next, error, complete), but it is also a producer (because it can pipe and consumers can subscribe to it) as it emits a new stream of data that can be consumed by the town. This is akin to a multicast where a single producer can emit values to multiple consumers. The factory processes the incoming stream and may re-process values (retryWhen) or discard them (filter) before emitting a new stream of purified data.
Schedulers are used to control the timing of the stream. They can be used to delay, throttle, or debounce emissions.
- In this thirsty scenario, we can see that if the dam’s control room blocks the flow of water entirely, this will affect the whole system downstream. If the control room were to stop the flow of water at night and schedule it to resume in the morning, this would be akin to a scheduler that controls the timing of the stream. This is useful to avoid flooding the system with too much data at once, such as when a user types in a search box and we want to avoid making too many network requests at once. We can use a scheduler to throttle the stream of data to only emit values every 500 milliseconds, for instance, although in many cases we can directly rely on time-based operators.
Unicast is a one-to-one mapping between the producer and the consumer. It’s the default behavior of RxJS.
- Assuming our dam blocks and redirects the entire stream coming from the glacier, then the initial part of the diagram would be a unicast with a single producer emitting values to a single consumer.
Multicast is a one-to-many mapping between the producer and the consumers. It’s the behavior of RxJS when using Subjects.
- If we take each resident of the town to be a subscriber of the water purification factory, then we have a multicast where a single producer emits values to multiple consumers. Likewise, the power utility company is a consumer of the electricity stream and a producer of a new stream that can be consumed by the town.
Cold observables are lazy and only start emitting values when subscribed to.
- In the case of the pond, it is a cold observable that only starts emitting values when a subscriber is listening to it, such as when a pump is plugged into it or someone fills a bucket of water from it.
- In the diagram, a person acts as an AsyncSubject: it will work for a time to get water from the pond, but once it’s done, it will emit a single value (the last value, i.e., the bucket) to all subscribers (let’s pretend for the sake of simplicity and for this metaphor to keep working that all subscribers effectively receive the exact same stream/value when it is emitted all at once). This is different from a BehaviorSubject where the last value is emitted to late subscribers upon subscription. Subscribers will not receive any values from an AsyncSubject until it completes and, as depicted, can also unsubscribe before the stream emits any value.
Hot observables are eager and start emitting values immediately, even if there are no subscribers.
- There is a part of the river that’s identified near the bottom-left corner as a hot observable, because whether there are subscribers or not, it will keep emitting values. A ReplaySubject – the cameraman – was added to capture the values emitted from the river and make them available to late subscribers right upon subscription (e.g., when they watch it live on TV at some point).

My representation of the world may be flawed as I haven’t gone out much since the pandemic. Yet, that drawing tried to encapsulate most of the RxJS ecosystem and to some extent, that of reactive programming.

Operators

Operators allow to hook into a stream, operate on it and even combine it with other streams.

Creation

They are standalone functions to create observables, such as of, from, fromEvent, interval, timer or range.
You should always clean up subscriptions by unsubscribing when they’re no longer needed to avoid memory leaks and unintended consequences.
fromEvent
- Can create observables from DOM events or Node.js streams.
of
- Values are emitted synchronously, one at a time.
from
- Values are emitted synchronously, looping through a provided iterable (i.e., object with a length property). Also works with promises (e.g., from(fetch(url))) or generators (function* () { yield … }).
interval and timer
- They can emit values over time as a timer, where timer is useful to specify a different delay on the first value being emitted (e.g., specifying the first argument to timer to be 0 to emit the first value immediately).
mapTo
- This is a shortcut to remap an input to a different output (e.g., a constant string).
filter
- It returns values when the evaluate to true from a function that itself returns a boolean value.
reduce
- It works exactly like Array.reduce. It will emit the final value once the observable completes. That means it needs a stop condition in the pipeline, such as reaching the end of a synchronous stream or taking a few values only from an infinite stream (e.g., interval(1000).pipe(take(3), reduce((acc, curr) => acc + curr) …)) to take the the sum of the first three values emitted after 3 seconds.
scan
- Just like reduce but emits every time the stream receives a new value, not just once the stream completes.
tap
- Used to spy on the observable source to perform side effects without affecting the underlying stream, which is useful when debugging to observe output values at different steps of the pipeline.

Pipe

Operators are comma-separated inside the pipe method that’s called on the observable. Then, the subscribe method is called on the assembled pipeline with a given observer to start producing the values from the stream.
The operators create a new observable at each step in a “pure” fashion, so that the original observable does not change. Each operator in the pipe is akin to a different step in an assembly line.
When subscribe is called, each operator in the pipe in turn subscribe to the observable and pass its value(s) along to the next operator in the pipeline.
map
- It’s similar to Array.map but it works on every element emitted from the stream, not on the stream as a whole.
finalize
- It is called once on the completion of the observable, which could be used to perform some cleanup logic after an action completes, such as updating a status field.

Filtering

take
- Accepts a given number of items from the source before completing.
first
- To take a single value based on a filtering condition.
takeWhile
- Emits values from the source observable as long as a predicate condition is met. A value of true can be passed to the second argument of the function signature of takeWhile to also emit the value that caused the stream to stop emitting. It is used to limit the lifetime of an observable based on a known condition to apply.
takeUntil
- It takes a value until another stream emits a value. It accepts as an argument another observable for this purpose.
distinctUntilChanged
- It will emit values only if they are distinct from the previously emitted value from the stream.
distinctUntilKeyChanged
- Will compare the previous value emitted with the current value to evaluate whether a given key of an object has changed.

Time-based

debounceTime
- Useful when you need the last value emitted within a short period of time, discarding all previously emitted values until enough delay has passed.
debounce
- Does the same thing as debounceTime, but allows passing a function so that variables can be used to determine the emission of results.
throttleTime
- Ignore values after the last emission for a specified duration, creating a “silence window”. It can help ignore spammy events by reacting after a certain time has passed only, such as listening for scroll events (e.g., do not process values instantly but rather every 20-30 ms).
- We can use asyncScheduler as the second parameter to throttleTime, and give it a config object as the third argument to specify whether we’re interested in emitting the leading (first) or trailing (last) event from the stream within the silence window (e.g., for a scroll event, we want to know the last position).
sampleTime
- It “samples” a time window to emit only the last value from that window, doing so at precise intervals.
auditTime
- This is like sampleTime, but starting a counter once the stream emits at least one value, keeping the last value emitted within the desired time window. This is the same as throttleTime where leading is set to false and trailing is set to true.

Transformation

One type of transformation operator is a flattening operator. This type of operator takes an observable that emits an observable to which RxJS internally subscribes to, simplifying the pipeline management. One such operator is mergeAll. Instead of mapping an emitted value to a new observable (e.g., with Ajax.getJSON) and then flattening the pipe to get the emitted value from that nested observable with mergeAll, we can do this in a single step with mergeMap.
mergeMap
- This is good for “fire and forget” type of behavior. For example, we may have an observable of click events from which we save the clientX and clientY coordinates, using these values to make an Ajax request that can perform an operation in the background which we do not want to cancel. Need to be careful with this as long-running observables may need cleanup.
switchMap
- While mergeMap can maintain any number of inner subscriptions at a time, switchMap will maintain a single one. Any time a new observable is mapped, the previous one is automatically completed. This is useful if a previous request needs to be cancelled where only the last request makes sense, such as in a type-ahead behavior where we don’t want results from previous requests to be shown, but rather only the last one. This is the safest default for flattening because it won’t create leaks like mergeMap, which will leave other inner observables running in the background unless they are explicitly completed.
  - Great for reset, pause and resume functionality.
  - Should avoid it when cancelling a request will have negative side effects, like saving a document.
concatMap
- Like switchMap, concatMap works on a single observable at a time, queuing up events (FIFO) from other observables until the first one completes. Should only be used when you have observables with a finite lifespan, otherwise the queue will never empty. This is useful when execution order of requests is important on the client side and when events will have a finite lifespan.
exhaustMap
- Only maintains one inner subscription at a time. It will ignore values from new events until the first observable completes, discarding those events while there’s still an ongoing active subscription. This could be used to prevent further requests when clicking a button such as when submitting a form, effectively “disabling” the button while the submission is happening to avoid spamming the server with duplicate requests.
catchError
- By default, when an observable throws an error, it will stop emitting values as the errors are not handled. It can catch and return the error or return an empty observable to ignore the current value, which prevents the stream from breaking and will continue emitting values.

Combination

Can join multiple observables into a single stream, such as when you need to perform calculations based on multiple stream inputs.
startWith
- Lets you prepend any value(s) at the beginning of the stream.
endWith
- Lets you append any value(s) at the end of the stream.
concat
- Useful to execute multiple observables in order. When the first one finishes, the second one starts. That may come in handy to manage UI animations and to complete network requests in order.
merge
- Creates a single observable from any other number of observables. This means that it emits all values from all the observables as a single stream as they occur. For example, if we have a countdown related to both a “start” and a “pause” button, we might want the same stream to return “true” values when “start” is clicked and “false” values when “pause” is clicked to determine the next step to take in the pipeline.
combineLatest
- Takes two or more observables, combining the latest value received from each one only once all the observables have emitted at least one value. This would be useful when all values depend on each other to produce a common result.
forkJoin
- It emits the last produced value from each observable subscribed to as an array. This is like combineLatest, but returning values only once all streams have completed. The observables can be wrapped with brackets to emit an object, where a property (key) can be assigned to the result of each observable (set as a value of the object). This is somewhat equivalent to Promise.all.
share
- It is used to “share” the result of a stream to all subscribers. This can be useful to avoid running heavy computations more than once.

Creating a custom operator

We can create a custom operator by creating a function that returns a function that accepts an observable and returns a new observable. While that might be a bit of an abstract explanation to follow, here is a basic example illustrating this concept.

 typescript
 
 
 
import { Observable } from 'rxjs';

export function multiplyBy(multiplier: number) {
 return (source: Observable<number>): Observable<number> =>
 new Observable((observer) => {
 const subscription = source.subscribe({
 next(value) {
 observer.next(value * multiplier);
 },
 error(err) {
 observer.error(err);
 },
 complete() {
 observer.complete();
 },
 });

 return () => subscription.unsubscribe();
 });
}

// Usage:
import { of } from 'rxjs';
import { multiplyBy } from './multiplyBy';

of(1, 2, 3, 4, 5).pipe(multiplyBy(2)).subscribe((value) => console.log(value));
// logs 2, 4, 6, 8, 10

Here is another example combining filter, map and reduce to create a custom operator that will filter out values from a stream, map them to a new value and then reduce them to a single value.

 typescript
 
 
 
import { Observable, filter, map, reduce } from 'rxjs';

export function filterMapReduce<T, R>(
 predicate: (value: T) => boolean,
 mapFn: (value: T) => R,
 reduceFn: (acc: R, curr: R) => R
) {
 return (source: Observable<T>): Observable<R> =>
 source.pipe(
 filter(predicate),
 map(mapFn),
 reduce(reduceFn)
 );
}

// Usage:
import { of } from "rxjs";

of(1, 2, 3, 4, 5)
 .pipe(
 filterMapReduce(
 // keep only even numbers (2 and 4)
 (value) => value % 2 === 0,
 // multiply each of these even numbers by 2 (4 and 8)
 (value) => value * 2,
 // sum all these values
 // accumulator is initialized to 0
 // so we get 0 + 4 for the first value
 // then 4 + 8 for the second value, which is returned
 (acc, curr) => acc + curr
 )
 )
 .subscribe((value) => console.log(value)); // logs 12

Marble diagrams

They are used to represent the behavior of operators. They can be used to test observables.
They allow comparing at a glance how a set of inputs maps to a set of outputs (i.e., which transformations are applied to the source stream).
An X represents an error and a vertical line | represents the end of emission of values from the input stream.

Subjects

A Subject is an Observable: it has both pipe and subscribe methods. A Subject is also an Observer: it has next, error and complete methods. Unlike Observables which are unicast (1-to-1 mapping with observers, each observer gets an independent stream of data), Subjects are multicast, meaning they broadcast the same information to any “listeners” (observers).
Multicasting operators include share, shareReplay and multicast.

BehaviorSubject

It allows delivering a seed/initial value to late subscribers such that a subscription happening at a later point can still receive the last emitted value upon subscribing.

ReplaySubject

It allows replaying the whole stream (or the last items desired via its first argument) to late subscribers, effectively providing a way to multicast (i.e., the stream is played only once and multiple subscribers can receive the values at once).
shareReplay
- This can be added to a pipeline and any subscriber to that stream will receive updates as if a ReplaySubject has been manually set up. For time sensitive matters where receiving a value too late isn’t useful, a second argument can be passed to shareReplay to only capture events within the last x milliseconds.

AsyncSubject

Only emits the last value to all subscribers when it completes.

Here is a real-world example of a setup making use of a BehaviorSubject from an Excel add-in. The goal is to perform some actions in the UI whenever the connection status of a WebSocket changes by using a subject, which can be subscribed to from another part of the add-in to perform the needed updates. Omitting the details of the WebSocket connection, the following code snippet shows how we can use a BehaviorSubject to keep track of the connection status and emit the latest value to late subscribers.

 typescript
 
 
 
import { BehaviorSubject, Observable, distinctUntilChanged } from 'rxjs';

export class ConnectionManager {
 private apiConnection$ = new BehaviorSubject<boolean>(false);
 private ws: WebSocket | null = null;

 // Expose connection status as an Observable emitting whenever the connection status changes
 get connectionStatus$(): Observable<boolean> {
 return this.apiConnection$.asObservable().pipe(distinctUntilChanged());
 }

 // ...

 private async connect(): Promise<void> {
 this.ws = new WebSocket('ws://localhost:8080/ws');

 this.ws.onopen = async () => {
 this.apiConnection$.next(true);
 };

 this.ws.onclose = async () => {
 this.apiConnection$.next(false);
 };

 this.ws.onerror = (error) => {
 // ...
 };
 }
}

In other words, we can subscribe to the connectionStatus$ observable and react to changes in the connection status. This is useful to update the UI, for instance, to show a “disconnected” message when the connection is lost.

In a state manager, this might be dealt with like this to keep track of the sheets we have:

 typescript
 
sheetSubscriptions.set(sheetId, new Subject()); // track the sheet subscriptions

// ...
// delete the subscriptions to the sheet at some point in the future
sheetSubscriptions.get(sheetId).next(); // unsubscribe from all subscriptions for this sheet

The implementation details of the sheetSubscriptions map are omitted here, but the idea is that we can use a Subject to keep track of the subscriptions to a given sheet. When we want to unsubscribe from all subscriptions to a given sheet, we can call next on the subject to complete the stream and unsubscribe from all subscriptions.

Schedulers

All schedulers accept three arguments: work (task to execute), delay (in milliseconds) and state (when used, the first argument work defines the function to execute and state the data passed to it).
Most basic observables (e.g., range) accept as the last argument a scheduler, so this can be set there (e.g., range(1, 5, asapScheduler)).
AsyncScheduler
- Can be used as an equivalent to setTimeout. It’s simpler to just use the delay operator for that purpose. When used with subscribeOn in the pipeline, this is equivalent to wrapping the whole observable with setTimeout.
asapScheduler
- This is used to queue micro tasks, which are run after other synchronous pieces of code but before asynchronous code.
- Micro tasks are run after the currently running synchronous code but will block the UI when run.
animationFrameScheduler
- This is similar to requestAnimationFrame. Set no delay or set it to 0 so that it will not be async and will update before every browser repaint.
queueScheduler
- It is synchronous by default. Inner calls to queueScheduler will be executed once the outer calls are done running.

While it’s possible to use schedulers directly to provide fine-grained control over concurrency, it’s often easier to use the delay operator to delay the emission of values from the stream. For instance, we can use delay(1000) to delay the emission of values by 1 second.

Example flow

 typescript
 
 
 
import {
 BehaviorSubject,
 EMPTY,
 Observable,
 Observer,
 Subject,
 catchError,
 distinctUntilChanged,
 filter,
 from,
 of,
 switchMap,
 tap,
} from 'rxjs';

// Create a subject (stream emitting AND receiving values over time) with a default
// value. A common pattern is to suffix the variable name with a `$` to indicate that
// it's a stream
const stream1Subject$ = new BehaviorSubject<boolean>(false);

// Get the observable (stream emitting values over time) from the subject
// Doing this, we can `pipe` and `subscribe` to the observable but we can't emit values
// with `next`, `error` or `complete` methods.
// We can also use the subject directly to emit values with `next`, `error` or
// `complete`.
const stream1Observable$ = stream1Subject$.asObservable();

// Will use to send the final result of the status$ observable to this second stream
const stream2Subject$ = new BehaviorSubject<string>('');
const stream2Observable$ = stream2Subject$
 .asObservable()
 .pipe(filter((value: string): boolean => value !== '')); // ignore initial/empty values

const stream3ObservableForErrorsSubject$ = new Subject<string>();
const stream3ObservableForErrors$ =
 stream3ObservableForErrorsSubject$.asObservable();

// Some async operation that will update the connection status
const asyncFuncOnStatusChanged = async (
 isConnected: boolean
): Promise<void> => {
 // ... `await` some async operation to update the UI with the new connection status
 console.log(` -> onStatusChanged: ${isConnected}`);

 if (!isConnected) {
 throw new Error('Disconnected!');
 }
 return Promise.resolve();
};

// Create an observable (stream emitting values over time) from an another observable.
// The idea is to transform the original event into another event:
// event1 -> event2 -> event3 -> ... -> result
// Any observer on these events could push new values into other streams
// (e.g. `otherSubject$.next("value")`)
const observable1GetConnectionStatusChangedForRibbon$ = (
 connectionStatus$: Observable<boolean>
): Observable<void> => {
 // Transform the original event with `pipe`
 return connectionStatus$.pipe(
 // Prevent the observable from completing when an error is thrown
 catchError((error) => {
 console.log(`Caught error in observable1: ${error}`);
 return of(false);
 }),
 tap((value) => console.log(` -> observable start: ${value}`)),
 // If the value is the same as the previous one, don't emit it
 distinctUntilChanged(),
 // Perform side effects with `tap` (useful for logging/debugging)
 tap((value) => console.log(` -> observable before switchMap: ${value}`)),
 // Ensure async execution
 switchMap((value) =>
 from(asyncFuncOnStatusChanged(value)).pipe(
 // This will catch errors thrown by `asyncFuncOnStatusChanged` in a 'local' way.
 // We would still need to catch errors thrown directly from the source observable
 // as we did above
 catchError((error) => {
 console.log(`Caught error: ${error}`);
 // Emit the error to the third observable
 stream3ObservableForErrorsSubject$.next('error');
 // This completes the inner observable
 return EMPTY; // EMPTY is an observable that completes immediately
 })
 )
 )
 );
};

// In this case, we could just as well have used `status$` directly,
// but this could be useful if we want to transform the original event or if we want to
// merge multiple observables into one
const stream1ObservableTransformed$ =
 observable1GetConnectionStatusChangedForRibbon$(stream1Observable$);

// Create an observer (object with `next`, `error` and `complete` methods) to subscribe
// to the observable
const observer1 = (): Observer<void> => {
 console.log(' -> observer: subscription started');
 return {
 next: () => {
 console.log(' -> observer: status changed');
 // We could trigger another event here to continue the pipeline elsewhere, e.g.:
 // otherSubject$.next("value");
 // Then, if there's a subscription to `otherSubject$`, it will receive the value
 // "value" and continue the pipeline
 },
 error: (error) => {
 console.error(` -> observer: subscription errored: ${error}`);
 },
 complete: () => {
 console.log(
 ' -> observer: subscription completed, notifying stream2Subject$'
 );
 stream2Subject$.next(
 'observer1 sent this message to observer2 in `.complete()`!'
 );
 },
 };
};

console.log('Subscribing to secondObservable$...');
const observer2 = (): Observer<string> => {
 console.log(' -> observer2: subscription started');
 return {
 next: (value: string) => {
 console.log(` -> observer2: got '${value}'`);
 },
 error: (error) => {
 console.error(` -> observer2: subscription errored: ${error}`);
 },
 complete: () => {
 console.log(' -> observer2: subscription completed');
 },
 };
};
const stream2ObservableSubscription = stream2Observable$.subscribe(observer2());

console.log('\nSubscribing to thirdObservableForErrors$...');
const stream3ObservableSubscription$ = stream3ObservableForErrors$.subscribe({
 next: (value: string) => {
 console.log(
 ` -> observer3: got value '${value}' from observer2.complete()`
 );
 },
 error: (error) => {
 console.error(` -> observer3: subscription errored: ${error}`);
 },
 complete: () => {
 console.log(' -> observer3: subscription completed');
 },
});

console.log('\nSubscribing to observable status$...');

// Subscribe to the observable. Until we subscribe, nothing happens!
stream1ObservableTransformed$.subscribe(observer1());
console.log('\nEmitting `true` to stream1Subject$...');
stream1Subject$.next(true);
console.log('\nEmitting `true` to stream1Subject$...');
stream1Subject$.next(true);
console.log('\nEmitting an error to stream1Subject$...');
stream1Subject$.error('Error emitted from the outside');

console.log('\nEmitting message to stream2Subject$...');
stream2Subject$.next('Sent unrelated message from the outside');

console.log('\nEmitting `false` to stream1Subject$...');
stream1Subject$.next(false);
console.log('\nEmitting `true` again to stream1Subject$...');
stream1Subject$.next(true);
console.log('\nEmitting `false` again to stream1Subject$, causing error...');
stream1Subject$.next(false);
console.log('\nStreams keep listening until completion or unhandled error');

// Add some async behavior so this will happen at the end
setTimeout(() => {
 stream3ObservableForErrorsSubject$.next(
 'Will receive one more value before unsubscribing'
 );
 console.log('\nUnsubscribing from thirdObservableSubscription$...');
 stream3ObservableSubscription$.unsubscribe();
 stream3ObservableForErrorsSubject$.next(
 'Will not be received after unsubscribe'
 );
}, 0);

stream1Subject$.complete();

console.log('\nEmitting `true` to statusSubject$...');
// This is ignored because the stream is completed by now
stream1Subject$.next(true);

// already unsubscribed since they completed: nothing will happen
stream1Subject$.unsubscribe();
stream2ObservableSubscription.unsubscribe();

This will result in the following output being logged to the console:

 
 
 
Subscribing to secondObservable$...
 -> observer2: subscription started

Subscribing to thirdObservableForErrors$...

Subscribing to observable status$...
 -> observer: subscription started
 -> observable start: false
 -> observable before switchMap: false
 -> onStatusChanged: false

Emitting `true` to stream1Subject$...
 -> observable start: true
 -> observable before switchMap: true
 -> onStatusChanged: true

Emitting `true` to stream1Subject$...
 -> observable start: true

Emitting an error to stream1Subject$...
Caught error in observable1: Error emitted from the outside
 -> observable start: false
 -> observable before switchMap: false
 -> onStatusChanged: false

Emitting message to stream2Subject$...
 -> observer2: got 'Sent unrelated message from the outside'

Emitting `false` to stream1Subject$...

Emitting `true` again to stream1Subject$...

Emitting `false` again to stream1Subject$, causing error...

Streams keep listening until completion or unhandled error

Emitting `true` to statusSubject$...
Caught error: Error: Disconnected!
 -> observer3: got value 'error' from observer2.complete()
 -> observer: subscription completed, notifying stream2Subject$
 -> observer3: got value 'Will receive one more value before unsubscribing' from observer2.complete()

Unsubscribing from thirdObservableSubscription$...

While this example is a bit abstract and contrived, RxJS can be used for a bunch of different use cases, including:

Use debounceTime and switchMap to limit requests and cancel previous searches in a search auto-complete;
Typeahead search box: fromEvent on keystrokes, combined with API requests;
Scroll position can be tracked with fromEvent to lazily load content;
combineLatest and map can be used to validate fields as user fills them out;
Progress bar updates could be animated using interval and map;
Use fromEvent to track mouse drags and merge to handle multiple event streams;
Create a real-time dashboard updating based on WebSocket streams with merge;
Debounce input changes with debounceTime to trigger saves;
Create heatmaps from click events using fromEvent and reduce;
Retry XHR requests on failure using catchError and retry.

Going back to the world of Excel add-ins, here is a real-world example of a setup using RxJS to listen to events from the Excel API. The goal is to listen to selection changes on a table and perform some actions when the selection changes. The fromEventPattern method allows us to create an observable from an API event. We basically “hook” into the Excel API event and transform it into an observable. We can then use the filter operator to filter out unrelated events and the takeUntil operator to unsubscribe when the notifier emits (when the table is deleted).

 typescript
 
 
 
import { Observable, Subject, filter, fromEventPattern, takeUntil } from 'rxjs';

const notifier$ = new Subject<void>();
const table = Excel.Table; // some actual table object (omitted for brevity)

const getTableOnSelectionChanged$ = (
 table: Excel.Table,
 notifier$: Subject<void>
): Observable<Excel.TableSelectionChangedEventArgs> => {
 return fromEventPattern<Excel.TableSelectionChangedEventArgs>(
 (handler: TAnyExcelValue) => table.onSelectionChanged.add(handler),
 (handler: TAnyExcelValue) => table.onSelectionChanged.remove(handler)
 ).pipe(
 // unsubscribe when notifier emits (table is deleted)
 takeUntil(notifier$),
 filter(
 // filter unrelated events...
 (event: Excel.TableSelectionChangedEventArgs) => event.address !== null
 )
 );
};

const observer = (tableName: string) => {
 return {
 next: (event: Excel.TableSelectionChangedEventArgs) => {
 console.debug(`Event triggered at ${event.address}`);
 },
 error: (error) => {
 console.error(`Subscription errored: ${error}`);
 },
 complete: () => {
 console.debug(`Subscription completed for table '${tableName}'`);
 },
 };
};

const selectionChanged$ = getTableOnSelectionChanged$(table, notifier$);
const subscriber = selectionChanged$.subscribe(observer);
// ... do something with the subscription

notifier$.next(); // unsubscribe from the observable and delete the table

Reactive testing

Reactive testing is a way to test observables. It can be done with marble diagrams or by subscribing and asserting values. While it’s more difficult to wrap one’s head around marble diagrams, they are more accurate and can be used to test timing. Subscribing and asserting values is easier to understand but requires more boilerplate and is less accurate.

Marble testing

We can test streams with expressive ASCII representations of marble diagrams.
This allows for greater test accuracy of values and timing.
It requires quite a bit of setup.
A dash - represents a frame of virtual time.
Any character from the set [a-z0-9] represents an emitted value.
Errors are represented with a #.
() represent synchronous groupings.
The | represents the completion of the stream.

Example

 typescript
 
 
 
import { delay, from } from 'rxjs';
import { TestScheduler } from 'rxjs/testing';

const testScheduler = new TestScheduler((actual, expected) => {
 expect(actual).toEqual(expected);
});

describe('testing async behavior', () => {
 it('should test asynchronous operations', () => {
 testScheduler.run((helpers) => {
 const { expectObservable } = helpers;
 const source$ = from([1, 2, 3]);
 const final$ = source$.pipe(delay(1000));
 const expected = '1s (abc|)';
 expectObservable(final$).toBe(expected, { a: 1, b: 2, c: 3 });
 });
 });
});

Less setup required.
Can use typical testing APIs and testing patterns.
Because this runs outside the test scheduler, we must manage async test completion.
Requires more boilerplate for assertions with multiple items.
Hard to accurately test timing.

Example

 typescript
 
 
 
import { map, of, toArray } from 'rxjs';

describe('testing with subscribe and assert pattern', () => {
 it('compare emitted values on completion', () => {
 const source$ = of(1, 2, 3);
 const final$ = source$.pipe(
 map((x) => x * 5),
 toArray()
 );

 const expected = [5, 10, 15];

 final$.subscribe((actual) => {
 expect(actual).toEqual(expected);
 });
 });
});

Tips and tricks

Using finalize to execute side effects on completion.
- Do not put side effects to run inside the complete function as it is not called when manually unsubscribing or when an error occurs.
- Instead, we can add the finalize operator tacked onto the end of the pipeline.
Extract common operator logic into standalone functions.
- These functions will accept an observable source and return a new observable. See Creating a custom operator for an example.
Use combination operators to access state from secondary streams.
- Use withLatestFrom(store$) to retrieve the current state. This works when subscribing to a BehaviorSubject which will have emitted the value by the time it’s needed but may be a source of headaches if subscribing to a regular Subject since the last value will not have been emitted by the time the subscription happens.
Automate observable cleanup with takeUntil and Subjects.
- While we can manually unsubscribe from observables and even unsubscribe from multiple observables at once by having a single subscription to which we add more subscriptions and then unsubscribe from, it is easier to react to a value emitted from a Subject like onDestroy$ by appending takeUntil(onDestroy$) to the pipeline. Whenever onDestroy$.next() is called, any subscription depending on it will unsubscribe automatically, then onDestroy$.complete() will clean up unused resources.
Use partition and filter for conditional logic.
- filter can be very useful when a single type of output is expected, filtering values before they reach the end of the stream.
- partition will return two observables, which we can destructure. The first one will filter and catch emissions that match our condition and the other stream will contain the values that didn’t match the condition. This is useful to avoid creating two different streams when there’s an if/else situation where two types of outputs would be expected.

Conclusion

RxJS is a powerful yet complex toolkit for managing asynchronous data flows. While the learning curve can be steep, the benefits are significant for reactive web apps and complex logic with many asynchronous operations. With practice, RxJS makes it possible to write declarative code that reacts to real-time data updates. By modeling everything as streams of data and applying transformations, RxJS helps tackle challenging programming tasks in a maintainable way. While it takes effort to master, reactive programming with RxJS might just be an essential skill for modern JavaScript/TypeScript developers working on reactive web applications!

Resources and references

Excel add-ins documentation, Microsoft
Learn RxJS, Learn RxJS
RxJS - Reactive Extensions Library for JavaScript, RxJS
RxJS & Reactive Programming, Josh Ribakoff
RxJS Marbles - Testing, RxJS
RxJS Marbles, RxJS Marbles

Uncovering some of the merits of text-based diagrams

Sébastien Lavoie — Sat, 19 Nov 2022 21:00:00 -0600

Introduction

Ever since I was introduced to text-based diagrams through UML and more concretely thanks to some fanatic acquaintance who shall remain nameless (else he will turn rufous), I was hooked by their simplicity, flexibility, predictability of presentation and usefulness. While they can be customized up to a point to look a bit better, the goal is really about efficiency. I came to peace with the fact that the final product will often look different from what I’d like to achieve. After all, one of the possible applications of text-based diagrams is to quickly share ideas that can be iterated upon without too much fuss and without slowing down to make things pretty. True, the arrows might not be placed precisely where I’d want them to show up, but the time savings gained by not having to re-arrange boxes and accommodate a canvas are hefty compensation prices! Besides, some tools in that space integrate really well on platforms like GitHub and GitLab without requiring any special piece of software to be produced or viewed, which makes them particularly convenient.

PlantUML: an old love affair

PlantUML has been around for a while – over 12 years at this point! It is a bit cumbersome to use as it requires a server running with Java to do its job. There are good integrations for it though, including a VS Code extension and a Docker image. Its documentation is pretty good and the diagrams are more easily configurable out of the box than with some other similar tools.

Even when starting with an unremarkable use case diagram such as the following one, ideas can be shared efficiently without having to go to a drawing board.

Actually, the code responsible for generating this diagram is as follows:

 
 
 
@startuml
package Users {
 :End User 1: as EndUser1
 :End User 2: as EndUser2
 :User:
 User <|-- EndUser1
 User <|-- EndUser2
}
package "End User actions" {
 (Escalate a case) as UC1
 (Mark a case solved) as UC2
 (Communicate with fellow citizens) as UC3
}

EndUser1 -- UC3
EndUser2 -- UC3
note bottom of UC1 : Under specific conditions,\ne.g. after X amount of time
@enduml

While this may look like an unfamiliar syntax at first, it is concise, expressive and can be used for many types of UML diagrams. For instance, to take a different use case a notch further, it is not much work:

 
 
 
@startuml
package Users {
 :Admin:
 :End User: as EndUser
 :User:
}
package "Admin actions" {
 (Identify users) as UC1
 (Forward complaints) as UC2
 (Give status update) as UC3
 (Mark case solved) as UC4
 (Notify by email) as UC5
}
package "End User actions" {
 (File a complaint) as UC6
}

User <|-- Admin
User <|-- EndUser
UC1 <-- UC6
UC5 <.. UC2 : << include >>
UC5 <.. UC3 : << include >>
UC5 <.. UC4 : << include >>
EndUser -- UC6
Admin -- UC1
@enduml

Sky is the limit! For example, drawing from scratch the following diagram may start to get messy when done manually:

This is when PlantUML starts to shine as it puts elements in sensible locations without one having to think about it – or endlessly tinker to make them fit on a predefined area. Regardless of the relative visual complexity achieved, the code behind the scenes is still quite understandable and manageable:

 
 
 
@startuml
package Users {
 :ISP:
 :End User: as EndUser
 :Admin:
 User <|-- EndUser
 User <|-- ISP
 User <|-- Admin
}
package "End User actions" {
 (File a complaint) as UC1
 (Receive update on complaint) as UC9
}
package "Admin actions" {
 (Forward complaint to ISP) as UC2
 (Receive feedback from ISP) as UC5
 (Notify End User of progress on complaint) as UC6
}
package "ISP actions" {
 (Receive End User complaint) as UC8
 (Reply to End User complaint) as UC3
 (Mark complaint solved) as UC4
 (Inform Admin) as UC7
}

UC1 --> UC2
UC2 --> UC8
UC3 ..> UC7 : << include >>
UC4 ..> UC7 : << include >>
UC8 <.. UC3 : << extend >>
UC3 <.. UC4 : << extend >>
UC7 --> UC5
UC5 ..> UC6 : << include >>
UC6 --> UC9
Admin -- UC2
EndUser -left- UC1
ISP -- UC8
@enduml

As can be seen, elements can be described on their own (here with a package) and linked together in a clear way (with custom arrows to specify the connection type, length and direction, e.g. -->, <.. or --). Of course, as with any programming task, it helps to adopt pertinent naming conventions…

Beyond use case diagrams, PlantUML is also nice for producing all sorts of outputs, for instance a component diagram (as seen in A retrospective on creating an impractical little tool just for fun):

It can also handle other types of diagrams: sequence; class; activity; state; deployment; network; etc. One other option that I have found useful is its ability to create Gantt charts that are easily programmable! This one, for example, which was used to distribute human resources across a small project done in a computer science degree at the University of London:

Its accompanying code was easy to re-use to cut parts of the diagram into sections that could be presented on their own:

 
 
 
@startuml
' Metadata
hide footbox
title Software Project Proposal — DefineBroadband
footer By Kris, Srijith and Sébastien
printscale weekly

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Coursework 1
-- Phase 1 --
-- Planning --
Project starts the 2020-11-02

[Discuss project] as [DP] starts 2020-11-02 and ends 2020-11-09
note bottom
 Define team rules, project ideation, setting Git, define set of tools, etc.
end note

[Competitor analysis] as [CA] starts 2020-11-16 and ends 2020-11-28
[User survey and results analysis] starts 2020-11-14 and ends 2020-12-04
[Market research] as [MR] starts 2020-11-09 and ends 2020-12-04
[Requirements modelling (UML)] as [RM] starts 2020-12-14 and ends 2020-12-20
[Requirements/Specifications] as [RS] starts 2020-12-04 and ends 2020-12-20
[Proposal writing: Part 1] as [PW1] ends 2021-01-09
[Review process] starts 2021-01-03 and ends 2021-01-09
[RS] --> [PW1]
[DP] --> [MR]
[MR] --> [RS]

-- Development --
[Prototyping design] as [PD0] ends 2021-01-04
[Investigate frameworks and online services] starts 2020-12-16 and ends 2021-01-06
[RS] --> [Prototyping design]

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Coursework 2
-- Phase 2 --
-- Planning --
[Proposal writing: Part 2] starts 2021-01-13 and ends 2021-03-13
note bottom
 Includes report and documentation
end note
[Verification and validation] starts 2021-01-25 and ends 2021-03-13
[Reflections on project] starts 2021-03-01 and ends 2021-03-13
[Final preparation] starts 2021-03-08 and ends 2021-03-13

-- Development --
[Writing software - TDD approach] starts 2021-01-11 and ends 2021-03-13
[Functional testing with users] starts 2021-01-25 and ends 2021-03-13

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
-- Development milestones --
[User Database] happens 2021-01-06
[User Registration] happens 2021-01-06
[Landing Site] happens 2021-01-20
[Initial Survey Collection] happens 2021-01-20
[Identifying your location on a map to update the GIS database] happens 2021-01-30
[Message Boards] happens 2021-02-15
[Regulatory Complaint Collection and Forwarding] happens 2021-03-10

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
-- Project milestones --
[Prototypes done] happens at [PD0]'s end
[Proposal delivery] as [PD1] happens 2021-01-11
[Project delivery] as [PD2] happens 2021-03-15
[PD2] displays on same row as [PD1]

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Closed days: holidays
2020-12-24 to 2020-12-25 is closed
2020-12-31 to 2021-01-01 is closed

' Closed days: margins before delivery
2021-01-11 is closed
2021-03-15 is closed
@enduml

It was in fact relatively frictionless to use this diagram as a template for a version 2:

This tool is incredibly awesome, yet it’s not as versatile as it could be. This is mainly due to the fact that while the output can be scaled as needed to get high quality diagrams, its format isn’t supported yet on GitHub (although GitLab does work with it without hassle). For this reason, I’ve looked elsewhere for greener grass and found an alternative for publishing on GitHub.

Mermaid: the new muse

Born roughly 4 years after PlantUML, Mermaid has seen some mesmerizing growth in the open-source world (currently at github.com/mermaid-js/mermaid, it has more than 7 times the number of GitHub stars that PlantUML has!). While I personally enjoy looking at the old-school output produced by PlantUML and have found that diagrams produced by it come out with better spacing and flows on average compared to Mermaid, I like even more the native GitHub support for Mermaid straight from Markdown files (by the way, GitLab supports both PlantUML and Mermaid)! It makes it a powerful tool to use because the diagram is embedded within the Markdown file itself, perfect to keep it under revision while avoiding commits with heavy binary assets.

Mermaid does not support as many diagram types as PlantUML, but it certainly works well for the main ones, which would include flowcharts, sequence diagrams, class diagrams, ER diagrams and Gantt diagrams. Its documentation is less dense and complete than that of PlantUML and diagrams are less customizable without messing around with external CSS files (which can’t be easily linked on every platform), but for the sheer convenience of being able to visualize diagrams from Markdown files on GitHub, it made it easier to switch over. Working locally with it is also a breeze as there is no need to point to a Java installation or have a server running from a Docker container when using, for instance, this VS Code extension.

Mermaid is great for flowcharts, although I have found myself in need of workarounds more often than with PlantUML for sure. For example, the following diagram was relatively painless to come up with:

As can be observed in its source code below, I had some issues with content alignment (plus, label positioning isn’t always optimal as can be seen with a particular ‘Yes’ in this case). That can often be fixed by changing the orientation of the diagram or by modifying the connection length between rectangles, but still.

 
 
 
flowchart TB

%% Define names
start[Start]
processReport[Process report]
uploadMetadata[Upload metadata]
triggerCloudFunction[Trigger Cloud Function]
convertCSV[Convert CSV to Feather]
lambdaFunctions[Lambda functions]

%% Square ones with single brackets take too much space
newReportQ{{New report?}}
newMetadataQ{{New metadata?}}
reportValidQ{{Is report and is valid?}}
csvFeatherValidQ{{Is metadata and is valid?}}
stop[Stop]

%% Outside subgraphs
start --> lambdaFunctions
uploadMetadata --> start
convertCSV --> start
newReportQ -->|No| stop
newMetadataQ -->|No| stop
reportValidQ -->|No| stop
csvFeatherValidQ -->|No| stop

subgraph AWS
lambdaFunctions --> newReportQ
lambdaFunctions --> newMetadataQ
end

%% Can't align properly without extra spaces...
subgraph &nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbspCloud function
triggerCloudFunction --> csvFeatherValidQ
newReportQ -->|Yes| triggerCloudFunction
newMetadataQ -->|Yes| triggerCloudFunction
triggerCloudFunction --> reportValidQ
end

subgraph VM 1
reportValidQ -->|Yes| processReport
processReport --> uploadMetadata
end

subgraph VM 2
csvFeatherValidQ -->|Yes| convertCSV
end

The syntax is straightforward to follow. Some shapes could take less space (the diamond/rhombus ones in particular), which is why I ended up using hexagonal nodes instead in this example. Overall, the experience is satisfying and makes it so easy to keep iterating and commit multiple versions of the work without taking much disk space at all in the Git repository! Admittedly, I’d rather work with PlantUML for other types of diagrams as I don’t personally use most of the ones Mermaid has to offer (e.g., pie charts, requirement diagrams, git graphs or user journeys) and I prefer the output from PlantUML for the other ones.

One thing I really like about flowcharts in Mermaid is how easy it is to nest graphs, which often increases clarity without making it difficult to create or update:

While this isn’t perfect, it’s good enough to show the architecture of a system at a basic level.

 
 
 
flowchart TB

%% Looping over regions to fetch and update
subgraph LoopOverRegionsUpdate[ ]

 %%%% Looping over days within each region
 subgraph LoopOverDaysUpdate[2.]
 loopDays[Fetch day metadata]
 updateRegion[Update region-level locally]

 loopDays
 -->|then| updateRegion
 --> loopDays
 end %%%%

fetchRegionMetadata[1. Fetch region metadata]

fetchRegionMetadata
-->|then, loop over days| LoopOverDaysUpdate
--> fetchRegionMetadata
end %%

%% Looping over regions to upload
subgraph loopOverRegionsUpload[ ]
forEachRegion[For each region]
uploadRegion[Upload metadata]

forEachRegion
--> uploadRegion
--> forEachRegion
end %%

%% Setting main node values
start[Automation runs]
spawns[Spawns VM to update metadata]
fetchTopLevelMetadata[Fetch top-level metadata]
updateTop[Update top-level metadata locally]
uploadTop[Upload top-level metadata]
resize[Resize instance group to zero to shut down] %%

%% Fetch and update steps
subgraph fetchAndUpdate[Fetch and update everything locally before uploading back to the bucket]
fetchTopLevelMetadata
-->|then, loop over regions| LoopOverRegionsUpdate
--> updateTop
end

%% Main flow
start
--> spawns
--> fetchAndUpdate
-->|once all processing is done, upload everything| loopOverRegionsUpload
--> uploadTop
--> resize %%

Well, it’s just a matter of taste and in reality, I wouldn’t use either PlantUML or Mermaid for fancier-looking results or for something that would be a real mess to follow textually. For these purposes, I would go with something like Draw.io or Figma, although with the recent acquisition of Figma by Adobe, I might have to switch to another option, like Framer or the promising open-source project Penpot.

When text-based is too clunky

Even though I love the possibilities offered by tools like PlantUML and Mermaid (we didn’t even touch on their theming capabilities!), there are instances where it’s just not as convenient. While it’s possible to do wireframing with PlantUML, there is no way it can compete with some software like Balsamiq on that front. Likewise, it’s going to be difficult to create customized diagrams like the following ones. With Figma, I could create this somewhat original-looking output:

Similarly, I could customize this ER diagram with Draw.io to get something that would be nearly impossible to do with text-based diagrams in terms of presentation:

Conclusion

Text-based diagrams are clearly not a panacea, but neither are they archaic vestiges with no modern use! When they are used for what they are good for – mainly UML diagrams – they get the job done quickly, consistently and appropriately based on UML standards that have been around for eons. They remove friction by not having to think about design and rather allow one to go deeper on the actual links to be created. While I’d often sketch early proposals roughly with pen and paper, I would take the next step in formalizing plans digitally with something like PlantUML or Mermaid. I would then jump from there as needed to other tools that are more flexible but also quite likely more time-consuming to create high-fidelity wireframes or mockups, but the key – in my mind at least – is to remember that different tools have different purposes and it’s nearly always a great idea to use the one best suited for the job.

Resources and references

A Guided Tour of an i3 Configuration

Sébastien Lavoie — Sat, 15 Aug 2020 10:51:00 -0500

Introduction

In Using i3 as a Window Manager for Increased Productivity, a number of reasons were given to get going with this fantastic tiling window manager. Now, it’s time to jump in and explore how to actually use i3! If you’re looking for an in-depth guide, the official i3 documentation or the i3 page on the Arch Wiki are awesome resources to dive deeper. Here, we’ll focus on day-to-day usage based on my current configuration file which I have used and refined over the past three years or so. I hope that you’ll be able to glean useful tips and tricks to apply to your own use case.

The Configuration File

To set keybindings, it may be handy to know the keycodes and their respective names. To get a full list, you can use xmodmap -pk in the terminal. If you’re not sure of the name of the key you want to press (is it “PageDown”, “PageDwn” or “Next”?), you can retrieve it by executing the xev command, which will open two windows: one for capturing the actual key press and the other one to display the relevant details for that key. For example, if you press the backspace key, the output will contain something like keycode 22 (keysym 0xff08, BackSpace). From there, you will know that a mapping would be of the form mod+BackSpace, where mod is the modifier of your choice that is usually specified at the top of the configuration file. Now we can start!

i3 config shortcuts

 bash
 
 
 
# Paths and names
set $brightness-laptop-down "light -U 1"
set $brightness-laptop-up "light -A 1"
set $brightness-monitor-default "python3 ~/.local/bin/monitor_brightness default"
set $brightness-monitor-down "python3 ~/.local/bin/monitor_brightness down"
set $brightness-monitor-up "python3 ~/.local/bin/monitor_brightness up"
set $brightness-toggle-laptop ~/.local/bin/toggle_laptop_brightness
set $default-web-browser brave-browser-stable
set $launcher-python-term ~/.config/ipython_launch.sh
set $launcher-temp-notes ~/.config/tmpnotes_launch.sh
set $launcher-todoist ~/.config/todoist_launch.sh
set $path-xrandr-both ~/.config/i3/run_xrandr.sh
set $path-xrandr-laptop ~/.config/i3/run_xrandr_laptop.sh
set $path-xrandr-monitor ~/.config/i3/run_xrandr_monitor.sh
set $screenshots-folder ~/Pictures/screenshots/
set $todoist-app-name "crx_elldfnmogicegdcphgljaoaklkpcnbnn"
set $toggle-mic-on-off ~/.local/bin/toggle_mic_source

# i3 specific
set $center-mouse exec ~/.config/i3/center-mouse
set $default-web-browser-class "(?i)brave-browser"
set $exec exec --no-startup-id
set $output-primary output eDP
set $output-secondary output HDMI-A-0
set $python-term "ipythonterm"
set $scratchpad-size 1920 1060
set $temp-notes "tmpnotes"
set $volumepath ~/.config/i3-volume/volume

# set mod key (Mod1=Alt, Mod4=Super)
# ⇒ the main modifier used to trigger shortcuts
set $mod Mod4

# Workspaces
#######################################
# Workspace names — can be customized with emojis and names
# ⇒ I find I like minimalism best and just mentally associate
# one workspace number with a specific type of task
# ⇒ those are set across all monitors
set $ws1 "1"
set $ws2 "2"
set $ws3 "3"
set $ws4 "4"
set $ws5 "5"
set $ws6 "6"
set $ws7 "7"
set $ws8 "8"
set $ws9 "9"
set $ws10 "10"

# Modes
#######################################
# set shut down, restart and locking features
# ⇒ type `$mod+Shift+Delete` then either `e`, `r` or `s`
mode "$mode_system" {
 bindsym e exec --no-startup-id i3-msg exit
 bindsym r exec --no-startup-id systemctl reboot
 bindsym s exec --no-startup-id systemctl poweroff

 # exit system mode with "Enter" or "Escape"
 bindsym Return mode "default"
 bindsym Escape mode "default"
}
set $mode_system (e)xit, (r)eboot, (s)hutdown
bindsym $mod+Shift+Delete mode "$mode_system"

# resize with smaller steps to get more control
mode "resize" {
 bindsym h resize shrink width 2 px or 2 ppt
 bindsym j resize grow height 2 px or 2 ppt
 bindsym k resize shrink height 2 px or 2 ppt
 bindsym l resize grow width 2 px or 2 ppt

 # exit resize mode: Enter or Escape
 bindsym Return mode "default"
 bindsym Escape mode "default"
}
bindsym $mod+r mode "resize"

# Show the next scratchpad window or hide the focused scratchpad window.
# If there are multiple scratchpad windows, this command cycles through them.
# There is an additional keybinding to allow a floating window to be toggled
# (recovered as a normal window).
# keycode 179 = F10 button
# (not the actual F10 key, but same button on my laptop with default function!)
mode "Scratchpad"{
 bindcode 179 scratchpad show, resize set 1920 1060, move position center; \
 scratchpad show, resize set 1920 1060, move position center
 bindsym $mod+Shift+space floating toggle; mode "default"
 bindsym $mod+Escape kill; mode "default"
 bindsym Escape scratchpad show; mode "default"
}
bindcode 179 mode "Scratchpad"; scratchpad show, resize set 1920 1060, move position center

# Caps Lock indicator, seen at
# https://www.reddit.com/r/i3wm/comments/k8m4k4/share_your_i3_tips_and_tricks_that_you_have/gf2lppd
mode "-------------------- CAPSLOCK --------------------" {
 bindsym Caps_Lock mode "default"
}
bindsym Caps_Lock mode "-------------------- CAPSLOCK --------------------"

# Sound
#######################################
set $statuscmd i3status

# Signal used to update the status line
set $statussig SIGUSR1

# Amount to increase/decrease volume as a percentage
set $volumestep 5

# Font
#######################################
# font for window titles
# ⇒ this is what you see in your i3bar
set $font-small font xft:Lato 12
set $font-medium font xft:Lato 14

# Set default font
$font-small

# Font used with Rofi (dmenu alternative)
set $rofi-font 'JetBrainsMono 16'

# Keyboard
#######################################
# Set the compose key to right Control
set $compose-key "compose:rctrl"

A few notes on the i3 config shortcuts:

This section appears at the top because it will affect how i3 works in general.
It makes extensive use of the set command so that all important shortcuts and paths to programs that could “break” if they are missing are easy to configure globally.
It sets all the different modes that i3 can use so it can be extended in one single place.
I use Alt in a few applications and reserve Super for the window manager only.
Find the font name you need with fc-list. For instance, to use JetBrains’ font: fc-list | grep Jet.

General settings

 bash
 
 
 
# launch a terminal
bindsym $mod+Return exec kitty

# launch a terminal in the same directory currently used
bindsym $mod+Shift+Return exec cd "$(xcwd)" && exec kitty

# kill focused window
# ⇒ usual way to close applications
bindsym $mod+Escape kill
bindsym $mod+mod1+Escape --release $exec xkill

# reload the configuration file
# ⇒ apply changes from this file on the fly
bindsym $mod+Shift+c reload

# restart i3 inplace
# ⇒ preserves your layout/session, can be used when upgrading i3
bindsym $mod+Shift+r restart

# exit i3
# ⇒ logs you out of your X session
bindsym $mod+Shift+e $exec i3-msg exit

# resize windows
# you can also use the mouse for that:
# for tiled windows ⇒
 # drag the border with LeftClick or RightClick
# for floating windows ⇒
 # `mod + RightClick`, then drag

# resize without entering "resize mode"
# ⇒ I find this more convenient. I usually don't care about
# precise window sizes, so here the steps are far greater.
# If I want more control, then entering resize mode will do.
bindsym $mod+Control+l resize shrink width 10 px or 10 ppt
bindsym $mod+Control+k resize grow height 10 px or 10 ppt
bindsym $mod+Control+j resize shrink height 10 px or 10 ppt
bindsym $mod+Control+h resize grow width 10 px or 10 ppt

A few notes on the General settings:

Resizing and moving floating windows with the mouse also works great: mod+LeftClick to move around and mod+RightClick to resize. This way, it’s also possible to move windows to other screens.

Screens and monitors

 bash
 
 
 
# lock the screens with a black color background
bindsym $mod+Delete $exec i3lock -c 000000

# hide/unhide i3status bar (laptop)
bindsym $mod+m bar mode invisible bar-0
bindsym $mod+Shift+m bar mode dock bar-0

# hide/unhide i3status bar (monitor)
bindsym $mod+b bar mode invisible bar-1
bindsym $mod+Shift+b bar mode dock bar-1

# set up displays
exec $path-xrandr-both

# use laptop display only (turn off monitor)
bindsym $mod+o exec $path-xrandr-laptop

# use monitor display only (turn off laptop screen)
bindsym $mod+mod1+o exec $path-xrandr-monitor

# use laptop + monitor displays
bindsym $mod+shift+o exec $path-xrandr-both

# disable screen saver
$exec xset s off

# disable power saving
$exec xset -dpms

A few notes on the Screens and monitors section:

It sets keybindings to hide/unhide bars on separate screens, which can be particularly useful when screen sharing without having to enter in fullscreen mode.
It has additional keybindings to turn on/off the displays independently.

Note: I rely on Vim keybindings to move between containers and workspaces as I find the position of those keys on the home row really comfortable to apply to the main window actions one would want to execute.

 bash
 
 
 
# container focuses where the mouse is (yes/no)
focus_follows_mouse no

# go to last urgent workspace
# ⇒ this is the worspace that turns "red" by default when something happens
# in an unfocused workspace, like an application pop-up
bindsym $mod+u [urgent=latest] focus; $center-mouse

# change focus
# ⇒ works in all modes: tabbed, stacked, etc.
bindsym $mod+h focus left; $center-mouse
bindsym $mod+j focus down; $center-mouse
bindsym $mod+k focus up; $center-mouse
bindsym $mod+Down focus down; $center-mouse
bindsym $mod+Up focus up; $center-mouse
bindsym $mod+l focus right; $center-mouse

# move focused window (works in all modes)
bindsym $mod+Shift+h move left; $center-mouse
bindsym $mod+Shift+j move down; $center-mouse
bindsym $mod+Shift+k move up; $center-mouse
bindsym $mod+Shift+l move right; $center-mouse

# for example, switching from workspace 1 to workspace 2 (e.g. mod+2) then
# typing again mod+2 would bring you back to workspace 1 without having to
# remember that you came from workspace 1 in the first place.
workspace_auto_back_and_forth no

# alternate between the last two workspaces that have been used
bindsym $mod+Tab workspace back_and_forth

# move a container (window or group of windows if you grouped them) to the
# "alternate" workspace you visited last
# (the one brought with $mod+Tab in this case)
bindsym $mod+mod1+Tab move container to workspace back_and_forth; \
 workspace back_and_forth

# switch to any window with Rofi
# ⇒ this simulates the familiar behavior of Alt+Tab on Windows and allows you
# to find windows by typing, but uses a better operating system to do it ;).
bindsym Mod1+Tab exec "rofi -theme lb -font $rofi-font \
 -show-icons -width 95 -show window"

# toggle fullscreen mode for the focused container
# ⇒ this hides the i3bar for the current monitor
# ⇒ you can still leave the i3bar hidden and switch to other workspaces
bindsym $mod+f fullscreen toggle

# navigate workspaces next / previous
# ⇒ works for all monitors and will go in increasing order
# if workspaces 1 to 6 are on monitorX and workspaces
# 7 to 10 are on monitorY as in this config, this will switch
# to any workspace where there is at least one container
bindsym $mod+Mod1+l workspace next
bindsym $mod+Mod1+h workspace prev
bindsym $mod+Shift+Right workspace next
bindsym $mod+Shift+Left workspace prev

# the difference with the above is that it limits movements to the
# the current monitor only
bindsym $mod+Right workspace next_on_output
bindsym $mod+BackSpace workspace next_on_output
bindsym $mod+Shift+BackSpace workspace prev_on_output
bindsym $mod+Left workspace prev_on_output

# Bindings to "mark" and "goto" mark specified with 1 character
# ⇒ rarely used, but can still be useful if you have many containers open
bindsym $mod+z exec i3-input -F 'mark %s' -l 1 -P 'Mark: '
bindsym $mod+g exec i3-input -F '[con_mark="%s"] focus' -l 1 -P 'Goto: '

# switch to workspace (no matter which monitor it is set to)
bindsym $mod+1 workspace $ws1
bindsym $mod+2 workspace $ws2
bindsym $mod+3 workspace $ws3
bindsym $mod+4 workspace $ws4
bindsym $mod+5 workspace $ws5
bindsym $mod+6 workspace $ws6
bindsym $mod+7 workspace $ws7
bindsym $mod+8 workspace $ws8
bindsym $mod+9 workspace $ws9
bindsym $mod+0 workspace $ws10

# determine which workspace appears on which screen
# ⇒ with a single output screen, this is not necessary
workspace 1 $output-secondary
workspace 2 $output-secondary
workspace 3 $output-secondary
workspace 4 $output-secondary
workspace 5 $output-secondary
workspace 6 $output-secondary
workspace 7 $output-primary
workspace 8 $output-primary
workspace 9 $output-primary
workspace 10 $output-primary

# move focused container to workspace and switch to workspace
bindsym $mod+Shift+1 move container to workspace $ws1; workspace $ws1
bindsym $mod+Shift+2 move container to workspace $ws2; workspace $ws2
bindsym $mod+Shift+3 move container to workspace $ws3; workspace $ws3
bindsym $mod+Shift+4 move container to workspace $ws4; workspace $ws4
bindsym $mod+Shift+5 move container to workspace $ws5; workspace $ws5
bindsym $mod+Shift+6 move container to workspace $ws6; workspace $ws6
bindsym $mod+Shift+7 move container to workspace $ws7; workspace $ws7
bindsym $mod+Shift+8 move container to workspace $ws8; workspace $ws8
bindsym $mod+Shift+9 move container to workspace $ws9; workspace $ws9
bindsym $mod+Shift+0 move container to workspace $ws10; workspace $ws10

A few notes on the Navigation section:

I like to keep the number of workspaces to 10 because the number row is easily accessible and there’s less context switching involved.
I also like to keep a higher number of workspaces on the main screen I work on as I can use mod+Left and mod+Right to switch focus on that screen only. This is usually to keep a reference opened on the other screen, like server logs.
Those keybindings make it really easy to navigate between workspaces on one particular screen. Even though I like to work with a monitor being higher than the laptop located in front of it to avoid working in a twisted position at all times, this would work fantastically well in the horizontal direction too.
If for whatever reason the main screen is disconnected (power outage or unplugged), I can still use the laptop screen without needing to modify the config file, although with a slightly more limited amount of workspaces. Tip: if a monitor has been disconnected (such as in the power outage scenario), using the keybinding to turn it off will move all the workspaces to the other display(s), so everything will be visible again.

Nice addition to make the mouse follow any focused container

By default, the focus of the mouse in i3 will go to the active screen, but it won’t follow the focus if switching to different containers on the same screen. I found this little hack using the center-mouse script after running commands like move and focus to force the mouse to move to any focused container. For convenience, here is the content of that script. You will need the program xdotool to use it.

Layout

 bash
 
 
 
# set default desktop layout (default is tiling), <stacking|tabbed>
workspace_layout tabbed

# change container layout (stacked, tabbed, toggle split)
bindsym $mod+s layout stacking
bindsym $mod+w layout tabbed
bindsym $mod+e layout toggle split

# start in opposite orientation from your monitor
default_orientation vertical

# toggle split at each new window (Fibonnaci layout)
# note: only useful if the layout is set to `default`
# for_window [class=".*"] split toggle

# toggle the way a split happens in the focused window
bindsym $mod+t split toggle

# toggle tiling / floating
# ⇒ this works on a container with any number of windows!
# if you select multiple windows with `$mod+a` (see below)
# to group them and then toggle them, the whole group will
# either tile or float
bindsym $mod+Shift+space floating toggle

# change focus between tiling / floating windows
# ⇒ If you leave a floating window on top of other tiled windows,
# you can switch the focus from the one on top to the one(s) in
# the background (useful with apps like Zoom or Google Meet that
# you want to keep in the foreground)
bindsym $mod+space focus mode_toggle

# Use Mouse+$mod to drag floating windows
floating_modifier $mod

# toggle sticky for floating windows
bindsym $mod+Shift+s sticky toggle

# focus the surrounding containers
bindsym $mod+a focus parent; $center-mouse
bindsym $mod+c focus child; $center-mouse

A few notes on the Layout section:

To maximize the size of applications, I prefer using the “tabbed” mode, which is more compact than the stacking mode. If I quickly want to split windows side-by-side, I just type mod+e to toggle split vertically by default and if I need a horizontal split, I just toggle again with mod+e.
I don’t use the “grouping” feature with mod+a and mod+c very often, but when I need to move a few windows to another workspace for instance, that’s quite handy!
A floating window in “sticky mode” will follow you on all your workspaces and remember that this mode is enabled even if you put in back in a tiling window and then to a floating window again.

Scratchpad

The scratchpad is sometimes so useful that it deserves its own section! When you send a window to the “scratchpad”, it disappears. Then, with a keybinding, you can bring in back in floating mode on top of any other window on any active workspace you happen to be in. The same keybinding will toggle on/off the display of that scratchpad and if you happen to have sent multiple windows to the scratchpad, activating the same keybinding again will cycle through all the scratchpads as we set a custom mode called Scratchpad in this example.

I often use that for an audio player I leave running in the background and instead of using a whole workspace to leave that window opened, I send it to the scratchpad, which means it doesn’t take any space and I can quickly bring it back in focus whenever I want, in any workspace. I find that having more than three windows in the list of scratchpads becomes cumbersome as you cycle through them, so I keep the scratchpad for specific, infrequent uses for applications that require less attention.

If you want to convert a scratchpad back to a regular tiled container, it’s as easy as triggering “toggle tiling / floating” (in this config file, it happens with mod+Shift+space).

 bash
 
 
 
# Move the currently focused window to the scratchpad.
# First, we toggle floating mode and we resize and position the window to make sure
# it will appear correctly when showing it for the first time.
bindsym $mod+minus floating toggle; resize set $scratchpad-size, \
 move position center; move scratchpad

# Set up scratchpad applications
for_window [class="Audacious"] floating enable
for_window [class="Audacious"] move scratchpad
for_window [class="Audacious"] resize set $scratchpad-size
for_window [instance=$temp-notes] floating enable
for_window [instance=$temp-notes] move scratchpad
for_window [instance=$temp-notes] resize set $scratchpad-size
for_window [instance=$python-term] floating enable
for_window [instance=$python-term] move scratchpad
for_window [instance=$python-term] resize set $scratchpad-size
for_window [instance=$todoist-app-name] floating enable
for_window [instance=$todoist-app-name] move scratchpad
for_window [instance=$todoist-app-name] resize set $scratchpad-size

A note on the Scratchpad section:

In my setup, I have two screens with the same resolution of 1920x1080, so the same “resize” command works on both screens. You might want to use two different keybindings if you want to bring a scratchpad back to a screen with a different resolution.

Borders

 bash
 
 
 
# Configure border style <normal|1pixel|pixel xx|none|pixel>
new_window pixel 5
new_float normal
default_floating_border pixel 5

# Hide borders
hide_edge_borders smart

# change borders
bindsym $mod+Shift+n border none
bindsym $mod+n border pixel 5
bindsym $mod+y border normal 5

A few notes on the Borders section:

I just love knowing which container is active, so I set thick, bright borders with a nice kind of “electric blue” color that’s easy to spot on a light or dark background (colors are set below in the section Colors & theming).
I also love saving space whenever possible to see more stuff on the screen, so I avoid gaps altogether (if you like them, have a look at i3-gaps). In that spirit, I also set the option hide_edge_borders smart so that borders don’t show up when I have only one tiled container covering the whole space.
This also shows that you can have a different border size for floating windows if you find the thickness distracting. Personally, I just find it helps me know which container is active when I toggle from foreground to background window with mod+space.

Bashtop on the left with a dark background, LibreOffice on the right with a light background, Neofetch floating window on top featuring a thick, blue border.

dmenu

dmenu is so useful that it also got its own section. By default, you usually launch applications with mod+d: I kept the same behavior here. I added a few custom launchers that I use all the time to open files based on a topic, using mnemonics that work (for me, at least). If you want to know more about setting these kinds of shortcuts, you may be interested in reading Using dmenu to Optimize Common Tasks ;).

 bash
 
 
 
bindsym $mod+Mod1+b $exec ~/Dropbox/.custom/dmenu/books.sh
bindsym $mod+Mod1+c $exec ~/Dropbox/.custom/dmenu/cheatsheets.sh
bindsym $mod+Mod1+d $exec ~/Dropbox/.custom/dmenu/documents.sh
bindsym $mod+Mod1+e $exec ~/Dropbox/.custom/dmenu/edit_scripts.sh
bindsym $mod+Mod1+f $exec ~/Dropbox/.custom/dmenu/filepaths.sh
bindsym $mod+Mod1+q $exec ~/Dropbox/.custom/dmenu/quotes.sh
bindsym $mod+Mod1+r $exec ~/Dropbox/.custom/dmenu/reading.sh
bindsym $mod+Mod1+s $exec ~/Dropbox/.custom/dmenu/scripts.sh
bindsym $mod+Mod1+u $exec ~/Dropbox/.custom/dmenu/university.sh
bindsym $mod+Mod1+w $exec ~/Dropbox/.custom/dmenu/work.sh
bindsym $mod+Shift+f $exec ~/Dropbox/.custom/dmenu/thunar_launcher.sh
bindsym $mod+Shift+u $exec ~/Dropbox/.custom/dmenu/university_launchers.sh
bindsym $mod+d $exec ~/Dropbox/.custom/dmenu/software.sh

Shortcuts

 bash
 
bindsym $mod+control+r $exec thunar ~/Desktop

# Display multiple time zones around the world
bindsym $mod+Mod1+t $exec ~/Dropbox/.custom/dmenu/times.sh

A few notes on the Shortcuts mini-section:

In i3, you don’t really make use of icons on the desktop. I like the absence of visual clutter it provides, but I sometimes like to access a specific folder in which I drop a few shortcuts/symlinks to access other files from there.
An idea for customization: working remotely with many teammates from around the world is sometimes confusing timewise, so I have a simple script that outputs the current time in the places I’m interested in monitoring.

Simple pop-up with a list of timezones.

Sound

 bash
 
 
 
# `pkill` is useful to quickly update the block in i3blocks
bindsym XF86AudioRaiseVolume exec $volumepath -np up $volumestep -t $statuscmd \
 -u $statussig && pkill -RTMIN+1 i3blocks
bindsym XF86AudioLowerVolume exec $volumepath -np down $volumestep -t $statuscmd \
 -u $statussig && pkill -RTMIN+1 i3blocks
bindsym XF86AudioMute exec $volumepath mute -n -t $statuscmd \
 -u $statussig && pkill -RTMIN+1 i3blocks
bindsym XF86AudioMicMute $exec $toggle-mic-on-off
bindsym $mod+exclamdown $exec $toggle-mic-on-off

# Automatically set the volume to a given value when (re)launching i3
exec_always --no-startup-id "amixer -D pulse set Master 50%"

# Always mute the microphone source when (re)launching i3
exec_always --no-startup-id pactl set-source-mute \
 "alsa_input.pci-0000_03_00.6.analog-stereo" true && \
 pkill -RTMIN+10 i3blocks

This section will depend on the hardware being used, but it gives an idea of how to do things. I use i3-volume to get nice notifications when changing the volume and all the options being set here use i3-volume. Toggling the mic output was not super obvious at first, but it’s obviously doable and it’s good to know there’s an XF86Audio property for that purpose!

Brightness

 bash
 
 
 
# Control brightness more precisely through software `light`
bindsym XF86MonBrightnessDown exec $brightness-laptop-down
bindsym XF86MonBrightnessUp exec $brightness-laptop-up

# Adjust external monitor brightness
bindsym $mod+F2 $exec $brightness-monitor-down
bindsym $mod+F1 $exec $brightness-monitor-up
bindsym $mod+F3 $exec $brightness-monitor-default

# Toggle laptop screen
bindsym $mod+Control+b $exec $brightness-toggle-laptop

To control the screen brightness, I use light. I also like to just toggle the brightness of my laptop at night when I read something on my external monitor, so I use a toggle_laptop_brightness script that I found somewhere online and adapted slightly.

Applications

This section will heavily depend on the software you use of course, but there’s the gist of it. I like to have a shortcut for bashtop to quickly monitor system resources (glances is also quite nice). Besides that, I like to have applications automatically appear on specific workspaces and be switched to in some instances.

Controlling which application opens in floating mode is also useful as some just don’t play that well with tiling. To find information about an application, you can open a new terminal window and launch xprop, click on the window you need information about and voilà, a couple of strings will be displayed like so (output truncated a bit):

	Icon (16 x 16):
	 ▒▓▓▓▓▒
	 ▒▓██████▓▒
	 ▒█▓▒░ ░▒▓█▒
	 ▒█▓░ ░▓█▒
	 ▓▓░ ░░░ ░▓▓
	▒█▒ ░███▓░ ▒█▒
	▓█░ ░░▓█▓ ░█▓
	▓█ ░▓▓██▓ █▓
	▓█ ▓█▒▓█▓ █▓
	▓█░ ▓█▓▓█▓ ░█▓
	▒█▒ ░▓▓▒▓▒ ▒█▒
	 ▓▓░ ░▓▓
	 ▒█▓░ ░▓█▒
	 ▒█▓▒░ ░▒▓█▒
	 ▒▓██████▓▒
	 ▒▓▓▓▓▒
WM_NORMAL_HINTS(WM_SIZE_HINTS):
		program specified location: 0, 0
		program specified minimum size: 627 by 279
		window gravity: NorthWest
WM_CLASS(STRING) = "audacious", "Audacious"
WM_ICON_NAME(STRING) = "47. David Bowie - Best Of Bowie - Heroes (3:36) - Audacious"
WM_NAME(STRING) = "47. David Bowie - Best Of Bowie - Heroes (3:36) - Audacious"

You may need to switch to tiling windows or make the terminal window that launches xprop a floating window to be able to click on the desired window. Here, we get an output for the Audacious music player. You usually need the second string from WM_CLASS(STRING) but if you don’t want to mess with letter casing being upper vs lowercase, you can prefix with (?i) for “insensitive” as shown below and that will match any window containing that pattern. Sometimes, you’re just after matching a “title” (like it’s done with LibreOffice in the snippet of code below) and you can get that one by showing the container’s border. With this config file, the mod+n keybinding will show the border you want at the top and mod+y will make it disappear again.

 bash
 
 
 
# Autostart applications
$exec $brightness-monitor-default
$exec $default-web-browser
$exec $launcher-todoist
$exec brightnessctl s 20%
$exec compton -CG --config /dev/null
$exec nitrogen --restore
$exec nm-applet
$exec pasystray
$exec xfce4-clipman

# First kill it as it doesn't always respect the `--timeout` option otherwise
exec_always --no-startup-id "killall unclutter; unclutter --jitter 40 --ignore-scrolling --timeout 5 &"

# Start
bindsym $mod+Shift+d --release exec "killall dunst; exec notify-send 'restart dunst'"
bindsym $mod+Shift+t exec thunar
bindsym $mod+Shift+w $exec $default-web-browser
bindsym $mod+masculine [instance=$python-term] scratchpad show; move position center
bindsym $mod+Shift+masculine $exec kitty --name ipythonterm -o font_size=22 -e \
 $launcher-python-term -q
bindsym $mod+plus [instance=$temp-notes] scratchpad show; move position center
bindsym $mod+Shift+plus $exec kitty --name tmpnotes -e $launcher-temp-notes
bindsym $mod+p [class="Audacious"] scratchpad show; move position center
bindsym $mod+Shift+p $exec audacious
bindsym $mod+q [instance=$todoist-app-name] scratchpad show; move position center
bindsym $mod+Shift+q $exec $launcher-todoist
bindsym Print --release $exec flameshot gui --path $screenshots-folder
bindsym $mod+Print --release $exec flameshot screen --path $screenshots-folder
bindsym mod1+F3 $exec kitty -e htop

# Open applications on specific workspaces
assign [class="(?i)code"] $ws1
assign [class=$default-web-browser] $ws3
assign [class="(?i)firefox"] $ws3
assign [class=$default-web-browser-class] $ws3
assign [class="Audacity"] $ws4
assign [class="Gimp"] $ws4
assign [class="Inkscape"] $ws4
assign [class="vlc"] $ws4
assign [class="(?i)atril"] $ws6
assign [class="(?i)zathura"] $ws6
assign [title="(?i)libreoffice"] $ws4
assign [class="Transmission"] $ws8
assign [class="keepassxc"] $ws8
assign [class="obs"] $ws8

# Automatically switch to workspace when opening those
for_window [class="(?i)code"] workspace $ws1
for_window [class=$default-web-browser] workspace $ws3
for_window [class=$default-web-browser-class] workspace $ws3
for_window [class="(?i)firefox"] workspace $ws3
for_window [class="Gimp"] workspace $ws4
for_window [class="Inkscape"] workspace $ws4
for_window [class="audacity"] workspace $ws4
for_window [class="vlc"] workspace $ws4
for_window [class="(?i)zathura"] workspace $ws6
for_window [class="(?i)atril"] workspace $ws6
for_window [title="(?i)libreoffice"] workspace $ws4
for_window [class="Transmission"] workspace $ws8
for_window [class="keepassxc"] workspace $ws8
for_window [class="obs"] workspace $ws8

# Open specific applications in floating mode
for_window [class="(?i)virtualbox"] floating enable border pixel 5
for_window [class="GParted"] floating enable border pixel 5
for_window [class="Lightdm-settings"] floating enable pixel 5
for_window [class="Lxappearance"] floating enable sticky enable border pixel 5
for_window [class="Nitrogen"] floating enable sticky enable border pixel 5
for_window [title="File Transfer*"] floating enable border pixel 5
for_window [title="alsamixer"] floating enable border pixel 5
for_window [class="(?i)zoom"] floating enable border pixel 5

The section Autostart applications is the list of applications that launch when you open your X session with i3.

Keyboard & mouse

 bash
 
# Set compose key to Right Ctrl
exec_always --no-startup-id setxkbmap -option $compose-key

# Delay, interval
exec_always --no-startup-id xset r rate 250 60

I like to set those options in my config file as they can be modified on the fly if you reload i3. This is thanks to the exec_always --no-startup-id directive which will always run the invoked command when relaunching, not just when logging in to a session.

Colors & theming

Of interest in this section, apart from the actual colors, is where you will set your i3bar on the screen (top vs bottom) and on which monitor your tray (the space with little icons to show the volume, WiFi connectivity and so on) will be displayed if you have more than one monitor. In this case, the bar displays at the top of the screen à la Mac or à la GNOME with position top and reveals information about system resources with i3blocks (you can find how it can be configured in my dotfiles or in the i3blocks GitHub repo).

 bash
 
 
 
# Start i3bar to display a workspace bar (plus the system information i3status if available)
bar {
 id bar-1
 $font-small
 $output-secondary
 # mode invisible
 tray_output none
 status_command i3blocks
 position top

 colors {
 background #000000
 statusline #ffffff
 separator #666666
# border backgr. text
 focused_workspace #4c7899 #285577 #ffffff #ffffff
 active_workspace #333333 #5f676a #ffffff #3c3b37
 inactive_workspace #333333 #222222 #888888 #aea79f
 urgent_workspace #2f343a #900000 #ffffff #ffffff
 }
}

bar {
 id bar-0
 $font-medium
 $output-primary
 tray_output primary
 status_command i3blocks
 position top
 bindsym button4 nop
 bindsym button5 nop

 colors {
 background #000000
 statusline #ffffff
 separator #666666
# border backgr. text
 focused_workspace #4c7899 #285577 #ffffff #ffffff
 active_workspace #333333 #5f676a #ffffff #3c3b37
 inactive_workspace #333333 #222222 #888888 #aea79f
 urgent_workspace #2f343a #900000 #ffffff #ffffff
 }
}

# Theme colors
# class border backgr. text indic. child_border
 client.focused #ffffff #ff0054 #ffffff #2e9ef4
 client.focused_inactive #333333 #8338ec #ffffff #484e50
 client.unfocused #333333 #000000 #bbbbbb #292d2e
 client.urgent #2f343a #900000 #ffffff #900000
 client.placeholder #F9FAF9 #061229 #FFFFFF #061229
 client.background #000000

What I’ve found particularly useful here is the fact you can have a different “i3 bar” for each screen. I’ve set keybindings in the section Screens and monitors so I can toggle them on/off separately too.

I’ve also switched away from the default i3status program to display the status bar(s) to i3blocks, which I’ve found a lot nicer to look at and easier to configure too.

Theming i3 can be tedious, but thankfully there are tools to automate the process! One such tool is i3-style, which allows you to quickly switch in place your theme without having to log out or modify manually your i3 config file. To go the manual route or to tweak an existing theme, you can always use a website like HTML Color Codes to find an exact hexadecimal value. You can also use terminal.sexy to come up with nice looking themes, which can be exported for other applications you may be using.

Conclusion

You can find the complete config file in my dotfiles on GitHub. If you liked this article, you may also enjoy reading the following ones:

More resources and references

Getting started with the i3 tiling window manager — Fedora Magazine
Official i3 documentation — i3wm.org
i3 page on the Arch Wiki — Arch Wiki

My Current Set of Tools and Customizations

Sébastien Lavoie — Sat, 06 Jun 2020 10:41:00 -0500

Category	#1 tool	Alternatives
3d animation	blender
audio editing	audacity
backup (script)	rsync
clipboard manager	copyq	clipman
cloud	dropbox-cli	google drive
code completion	coc.nvim	ale
code snippets	github gists	gitlab snippets
cursor hider	unclutter
desktop environment	xfce	gnome
diagram generation	plantuml	mermaid-js
dotfiles management	git bare repo
dynamic menu	dmenu	rofi
ebook manager	calibre
encrypted paste bin	paste.sh
file manager	thunar	pcmanfm, nautilus
file renamer	pyrenamer	thunar bulk rename
flowchart design	draw.io
fonts monospace	jetbrains mono	iosevka
fonts monospace	source code pro	inconsolata
fonts sansserif	lato	dejavu
gif screen recorder	peek
image editing (raster)	gimp
image editing (vector)	inkscape
interface design	figma
irc chat	hexchat	pidgin
latex typesetting	latex workshop	vimtex
linux distribution	xubuntu	debian, manjaro
memorizing	anki
mind mapping	freeplane	draw.io
music player	audacious	clementine
note-taking	vimwiki
notifications	xfce	dunst
office suite	libreoffice
operating system	gnu/linux	macOS
paragraph formatter	par
partition manager	gparted
password manager	keepassxc
pdf editing (minimal)	pdfarranger
pdf viewer	atril	evince, zathura
publishing	scribus
python documentation	sphinx
python formatter	black
python ide	pycharm
python linter	pylint
python refactoring	rope
python test suite	pytest
python virtualenv manager	venv module	virtualenvwrapper.sh
screen locker	slock	xflock4
screen recorder	obs studio	simplescreenrecorder
screenshot software	flameshot	xfce4-screenshooter
security	gnupg2
sound system	pulseaudio
source code explorer	sourcetrail
sql client	dbeaver
sql database	postgres	mysql, sqlite
sql viewer	sqlitebrowser
static website generator	pelican
task management	todoist	google keep
terminal calculator	ipython	bc
terminal clipboard	xclip
terminal coursera downloader	coursera-dl
terminal disk usage	ncdu
terminal emulator	kitty	st, xfce4-terminal
terminal file archiver	p7zip
terminal file lister	exa
terminal file lister tree-style	tree
terminal file manager	vifm	nnn
terminal file manager (minimal)	lf
terminal file viewer	bat	cat
terminal fuzzy finder	fzf
terminal markup converter	pandoc
terminal network downloader	wget
terminal network tool	curl
terminal partition manager	parted
terminal search tool	the silver searcher	locate
terminal session recorder	asciinema
terminal shell	zsh	bash
terminal system monitor	bashtop	glances, htop
terminal youtube downloader	youtube-dl
text editor	neovim	vim, vs code
torrent	transmission	deluge
version control stats	gitstats
version control system	git
video player	smplayer	vlc
visual plotting	geogebra
wallpaper browser/setter	nitrogen	feh
web browser	google-chrome	firefox, brave
window manager	i3	dwm
window manager status bar	i3blocks	i3status

For a more granular selection of open source projects I’ve used and like (Vim plugins, color schemes, command-line tools, etc.), you can also have a look at the GitHub repositories I’ve starred over time.

Tip the Scales in Times of Instability With the Rock-Solid Debian

Sébastien Lavoie — Sun, 05 Apr 2020 12:14:00 -0500

Introduction

I’m familiar with Linux distribution hopping, having tried out many options over the years, starting around the time Mandrake 9.2 was popular back in 2003, then switching to a few others including Ubuntu, KNOPPIX, Fedora, Xubuntu, openSUSE, Kubuntu, Mint, Manjaro, Mandriva… And of course Debian along the way, which undoubtedly used to be relatively harder to get started with.

My heart has also been stirred by different desktop environments and window managers, from more user-friendly/feature-rich solutions such as KDE, GNOME (along with Unity when it was still a thing), Xfce and Cinnamon to an arguably more obscure selection comprising Openbox, Fluxbox, Enlightenment, Awesome WM, dwm, i3 and bspwm.

I haven’t tried everything that’s out there (XMonad being one such esoteric possibility), but I’ve come to realize that what matters most to me is a great balance of stability and usability, allowing to be more focused on any given task at end and therefore leading to increased productivity. For this reason, I recently turned back to a fantastic combo: Debian with an Xfce base and the i3 tiling window manager.

Why Debian?

Stability and Reliability

Debian has always been to me the father figure of stability in the Linux world. Countless servers have run on Debian and continue to do so for good reason: it just works once it is properly set up. I have had some bad luck with other Debian-based distributions like Ubuntu and Linux Mint which strive to be easier to use but remain easier to break, being a bit more bleeding edge and sometimes bloated too with tons of software I don’t really need. Fedora, although I like its philosophy and style very much, has always lead to hardware issues on my apparently less-than-ideal machines. Manjaro has been pleasant and easy to use, but Arch feels like the right choice if one is to build a custom system from scratch. It does take a good amount of time to get things going on such a distribution and usually a good dose of maintenance too, which brought me to seek less time-consuming options. For stability and reliability, Debian is hard to beat in my experience.

Marvelous Package Manager

I have always found the package manager on Debian (and derivatives) to be easier to use than alternatives like yum, DNF or urpmi for RPM packages. The pacman package manager available on Arch-based systems is truly excellent and powerful, but I simply find apt to be more intuitive after using it for a lot longer.

It Just Won’t Break

Sitting on the bleeding edge is fun and sometimes even rewarding when things finally work as expected, but I have seen that it doesn’t stay that way forever. Big updates, sometimes relatively frequent ones, can leave the system in an unusable state. It’s often a minor annoyance to fix, but that just doesn’t happen on Debian, where packages are vetted mainly for their legendary stability before releasing them. They are indeed quite a bit older than what can be found on other distributions. It’s the price to pay, but I came to the conclusion that it’s worth it if you’re looking to get things done in the long run.

Debian Xfce in its glorious simplicity.

Xfce Is Minimalist Enough and Hassle-Free

It’s also about the combination of Debian + Xfce: while Debian makes sure the system remains functional as a whole, Xfce is the solution for interacting with applications and windows without glitches in a “floating mode” where all windows can be grabbed and moved around easily. Debian itself keeps old packages around by choice and Xfce has a very slow release cycle yet also provides stability out of the box. This means that installing Xfce on Debian has to work because bugs have been evened out over years of effort from both teams. This is an easy yet very satisfying solution.

Xfce vs KDE

One of the main appeals of desktop environments like KDE and GNOME is that they have more features and add them more often. They do use more resources and even though they have gone through substantial optimizations over the years, they still feel less snappy on older systems compared to simpler window managers or even Xfce. Recently, KDE caught up with Xfce in terms of resources utilization, but there’s one major reason I just can’t rely on it on a production machine: in every single release I have tried (from KDE 2.x in the early 2000s to Plasma 5.x), I was confronted with numerous bugs within minutes of delving into it. I have always been faced with some minor troubles on GNOME too (versions 2 and 3), but it’s never been as severe as with KDE. KDE has plenty of cool ideas and is fully customizable, but that’s to a fault in my view.

Xfce vs GNOME

On the other hand, GNOME does consume at least twice as much RAM and CPU compared with Xfce even with no extensions enabled on GNOME and a couple of plugins activated on Xfce. I enjoy how GNOME deals with virtual desktops and think this can be a great productivity enhancement, but once I’ve configured Xfce to be mainly keyboard-driven, I prefer keeping it simpler with less transition effects and other nice visual additions. On the graphical side of things, GNOME with Wayland has never worked as well for me as with Xorg, so that’s something else to watch for.

Xfce vs i3

Well, i3 is a different beast in its own right and has taken a special place in my heart. It uses less memory and CPU than any desktop environment out there and can be used with minimalistic software, like the st terminal and the dynamic menu dmenu (read the article about suckless tools if that resonates with your style!). There are still a few things that I didn’t like very much about it, such as the way windows are managed in fullscreen mode, the default lack of a convenient master/slave tiling layout (similar to dwm and bspwm) and the way one interacts with external monitor(s), where workspaces use the same numbering across multiple screens. But i3 with Debian feels more mature and is (again) a bit older than what you might find elsewhere. There is a comprehensive section in the i3 User’s Guide that explains how to work around some issues.

I find that maximizing windows works like what you would expect in Xfce, covering everything but the menu bar. There’s also the fact that Xfce makes it very convenient to add and remove virtual desktops on the fly instead of having a bunch of those at all time. With minimal Bash scripting, windows in Xfce can be moved around from one monitor to the other, replicating a useful feature available in i3. Xfce, having only floating windows, behaves better with applications like VirtualBox and GIMP by default. And there’s also some common ground with the “pseudo tiling” available in Xfce which makes i3 much less unique, although i3 makes it a lot easier to maximize the screen estate being used.

Debian i3 using up to the last available pixel.

In the department of customization, i3 is very good, but having to edit a configuration file manually each time a little change is desired can become tiresome. Xfce has a wonderful settings manager which makes it easy to adjust many system settings as well as those related only to the window manager. i3 requires initially quite a bit more effort to work and will incur a few additional dependencies if one wants to make it look better. Xfce strikes a very good balance: it’s highly customizable; pretty much bug-free in my experience and is usable right away without any surprise. Once both are fully configured to match one’s need, I tend to rely on i3 to be more productive and keep Xfce as a functional backup if someone else is going to try to use the mouse on my system to accomplish any kind of useful action with the windows ;).

I find that installing Debian with an Xfce base leads to having enough useful software pre-installed compared to a barebone installation and installing i3 afterwards only makes the transition easier.

Xfce vs Other Window Managers

Now, there is an endless stream of other options to explore and I don’t know enough about many of those to dare to comment. But from those I tried, I can certainly say that I preferred the ease of use of Xfce over other more minimalistic approaches like Openbox, Enlightenment and Fluxbox. Xfce offers all you need out of the box, but not much more, which is what I’m looking for at this moment. On the other hand, making dwm work in one precise way can be tricky and requires many tweaks before the configuration can remain untouched for a while. I do not like the necessity of recompiling the source code every single time a tiny change is made which led me to discard it as a convenient option in the long run. I like making small visual adjustments to my system from time to time and I want this to be as frictionless as possible.

Otherwise, dwm and bspwm might be some very decent options if one is inclined to be tweaking everything from scratch (it’s not really a facultative step anyways!), but Xfce integrates everything one might need under very few different packages and has been extremely reliable for me from the beginning. On any kind of modern machine, the extra system resources used up by Xfce compared to those lighter alternatives really don’t mean much in the end because it is compensated with the presence of useful applets and tools which definitely make one’s life easier.

It’s Ideal for Developers

Resources Efficiency & Effectiveness

Debian with a light working environment is resource-efficient and comes with much less software out of the box compared to the KDE or GNOME editions: instead, more resources are available for hungry applications like heavy IDEs. Installing applications specific to those desktop environments work flawlessly too. Not only does Debian consume less resources (especially while running Xfce/i3 on top), it does so extremely well and offers great performance.

Debian Xfce mostly at rest.

Rock-Solid Stability (Again, Big Selling Point!)

Since it’s so stable, any release of Debian is currently supported for at least 3 years and up to 5 years for LTS (Long Term Support) releases, which means one doesn’t have to worry about constantly upgrading the system. For a start, upgrading packages on the stable branch of Debian very rarely leads to a broken system, unlike on more bleeding edge distros like Fedora or Manjaro where downloading a few months old release almost guarantees some unexpected challenges.

Packages Availability

With currently close to 58,000 packages offered on Debian, there’s a very good chance that anything one might need will be available. Working with up-to-date, proprietary applications like Google Chrome, Zoom or Slack is also pain-free: most companies, when they do consider Linux, opt for sharing a classic deb package, the format used on Debian and Debian-based systems. Some of those packages can also be found or added directly to the sources managed by the package manager, allowing for easy, automatic updates.

Synaptic, the legendary package manager.

Large Community with Freedom in Mind

Because no company backs Debian directly, it relies on a community effort to keep going and it has done so for a long time, having now hundreds of distributions being based on it. This means that it’s easy to find a ton of documentation and tutorials giving solutions taking into account Debian-based systems. One will be able to fix any issue cropping up thanks to the Debian User Forums and of course thanks to the immense popularity of Ubuntu, which contributes tremendously to making answers available in its forums and in the Stack Exchange network.

Resources to Get Started

Debian Documentation
Debian User Forums
Debian Wiki
Developer-oriented: resources for contributing to Debian
Cloud-oriented: tutorials for Debian on Digital Ocean
i3 tiling window manager
Xfce Desktop Environment

Conclusion

After trying many different Linux distributions and desktop environments, I keep coming back to what satisfies me best in the end: stability and usability. Debian feels a bit old, but at the same time one knows it delivers on what it promises. The same can be said for Xfce and i3. This is also what makes them such a good combo: despite not being cutting edge in the realm of features, there’s no way it could break as easily as KDE or GNOME, particularly on less stable distributions. There are still a few rough edges when it comes to customizing both Xfce and i3 in my opinion, but when looking for something that just works and will keep doing so, Debian is hard to beat.

Suckless: Minimalist Tools That Work Great

Sébastien Lavoie — Sun, 12 May 2019 22:50:00 -0500

What are Suckless tools?

From the official website:

Home of dwm, dmenu and other quality software with a focus on simplicity, clarity, and frugality.

There are also other incredible pieces of software that are worth mentioning, including st.

Here, I will only go over the tools I use frequently, but keep in mind that everything from Suckless… Sucks less.

st — Simple Terminal

I did not know what to expect from this terminal and I found it delivers what I need! Configuring it is quite different than other terminals like Konsole or GNOME Terminal: you just edit a text file and compile the software before you can even use it. It may seem tedious at first, but compiling such a small piece of software is very fast and it needs to be done on seldom occasions when you may want to adjust a setting.

I have experienced rendering issues when scaling the text with other terminals (including Konsole), where some weird flickering would happen at certain font sizes. Simple Terminal just works without hassle. It doesn’t have much bells and whistles out of the box, but it can be patched to extend its functionality if you know what you are doing. I don’t, so my compiled version remains pretty basic although I must say I like the simplicity of it very much.

Configuration

I didn’t have to adapt the configuration file very much. I ended up changing mainly the following lines:

 cpp
 
 
 
static char *font = "Consolas:pixelsize=18:antialias=true:autohint=true";

static char *shell = "/bin/zsh";

/* Terminal colors (16 first used in escape sequence) */
static const char *colorname[] = {

 /* 8 normal colors */
 [0] = "#1c1c1c", /* black */
 [1] = "#ff005b", /* red */
 [2] = "#70e502", /* green */
 [3] = "#fcdd11", /* yellow */
 [4] = "#00a0ea", /* blue */
 [5] = "#bd1efc", /* magenta */
 [6] = "#14ecfc", /* cyan */
 [7] = "#ededed", /* white */

 /* 8 bright colors */
 [8] = "#666666", /* black */
 [9] = "#ff00a0", /* red */
 [10] = "#5dff00", /* green */
 [11] = "#ff9f00", /* yellow */
 [12] = "#71a9fc", /* blue */
 [13] = "#d571fc", /* magenta */
 [14] = "#6cf2fc", /* cyan */
 [15] = "#fcfcfc", /* white */

 /* special colors */
 [256] = "#0a0500", /* background */
 [257] = "#e0e0e0", /* foreground */
};

/*
 * Default colors (colorname index)
 * foreground, background, cursor
 */
unsigned int defaultfg = 257;
unsigned int defaultbg = 256;
static unsigned int defaultcs = 257;
static unsigned int defaultrcs = 256;

/*
 * Colors used, when the specific fg == defaultfg. So in reverse mode this
 * will reverse too. Another logic would only make the simple feature too
 * complex.
 */
static unsigned int defaultitalic = 7;
static unsigned int defaultunderline = 7;

/*
 * Default shape of cursor
 * 2: Block ("█")
 * 4: Underline ("_")
 * 6: Bar ("|")
 * 7: Snowman ("☃")
 */
static unsigned int cursorshape = 2;

/*
 * Default columns and rows numbers
 */

static unsigned int cols = 80;
static unsigned int rows = 24;

dmenu

dmenu can be configured in the same way as Simple Terminal by editing a text file and compiling the software. I like to use many keyboard shortcuts, but I find that for launching applications I don’t use that often or to launch custom Bash or Python scripts on the fly, nothing beats the simplicity of dmenu.

Configuration

This one is very easy to configure and doesn’t really require any attention at all besides defining where you want it to appear on the screen and what colors you prefer. Here are some smalls changes I made to the configuration in config.h before compiling it:

 cpp
 
 
 
static int topbar = 1; /* -b option; if 0, dmenu appears at bottom */
/* -fn option overrides fonts[0]; default X11 font or font set */
static const char *fonts[] = {
	"Consolas:size=12"
};
static const char *prompt = NULL; /* -p option; prompt to the left of input field */
static const char *colors[SchemeLast][2] = {
	/* fg bg */
	[SchemeNorm] = { "#D8D8D8", "#000000" },
	[SchemeSel] = { "#000000", "#ff7400" },
	[SchemeOut] = { "#000000", "#00ffff" },
};
/* -l option; if nonzero, dmenu uses vertical list with given number of lines */
static unsigned int lines = 0;

/*
 * Characters not considered part of a word while deleting words
 * for example: " /?\"&[]"
 */
static const char worddelimiters[] = " ";

slock

What can be said about slock? It just works and never gets in your way. Set it and really forget it. From the official page:

This is the simplest X screen locker we are aware of.

Again, its simplicity is charming and nothing really needs to be changed in config.h apart from colors and setting the correct username and group name to lock and unlock the screen.

Conclusion

This was a lighting fast overview of some of the tools I now use on a daily basis. Suckless tools caught my attention and kept it! They offer other specialized software like a web browser, a tool for presentation from the terminal, IRC client and others… but the ones described here are really those which I now can’t live without.

I was originally inspired to seek out those tools thanks to Luke Smith, a fantastic YouTuber.

Surfing with qutebrowser — a Keyboard-Driven Web Browser

Sébastien Lavoie — Mon, 11 Feb 2019 14:46:00 -0600

What is qutebrowser?

qutebrowser is a web browser that makes great use of Vim commands to navigate. From its website:

qutebrowser is a keyboard-focused browser with a minimal GUI. It’s based on Python and PyQt5 and free software, licensed under the GPL. It was inspired by other browsers/addons like dwb and Vimperator/Pentadactyl.

Why use it?

Perfect companion to any Vim user

The first notable feature of qutebrowser is obviously how well the use of keyboard shortcuts is integrated with the experience of using the software (there is a useful key binding cheatsheet on the homepage). Search bindings (/, n/N, ?), visual mode (v), tabs (gt, T), copy (yy), open URLs (o/O), J and K for switching tabs, etc. Many key bindings will look familiar to Vim users.

It even features a command mode, accessible by typing :, just like with Vim. Settings can be set from there directly, help can be accessed by typing :help [command/setting], the configuration file can be customized on the fly, the position and size of tabs can be set in many ways, history and settings page can be accessed and navigated through like any other page (hjkl, Ctrl + d, Ctrl + u, gg, G), etc.

Even though it is based on Python which is a “slow” language, most of the libraries and the web engine rely on C++ and the end result is a fast and powerful browser that’s totally customizable… Not unlike Vim.

Minimal interface ⇒ more space

Until I upgrade my laptop to a larger screen (≥ 17 inches), my current setup with its 15 diagonal inches benefits tremendously from configuring all applications to use pixels as efficiently as possible — which is why I now use exclusively [i3 as a window manager](/posts/2019/01/08/using-i3-as-a-window-manager-for-increased-pr oductivity/).

qutebrowser doesn’t even have a menu bar. By default, it only displays a small tab bar at the top (which can be moved to another side or removed) and a thin status bar at the bottom to see the URL, the current position in the page expressed in percentage, the number assigned to the current tab, etc. There is also a fullscreen mode available like in most other web browsers with the key F11, which will remove any window decoration and leave you in a (possibly) productive mode.

History, bookmarks and quickmarks

The history page (:history), while being minimal like all the rest, loads extremely fast and is a joy to navigate. The bookmarks page (Sb) is equally simple yet useful. The way I like to open a bookmark is in a new tab by typing gB (go bookmark as a mnemonic. Note that usually all uppercase letters open or do some action in a new space, such as a window or a tab).

Where qutebrowser shines in my opinion is with quickmarks. This is a simple but genius way to find what you are looking for: you type b (or B for new tab) to open a list of pages that are defined with a keyword, you type that keyword (or can type anything to search for a page), move around with arrow keys if necessary to select a page, type Enter and there you go. As far as I know, Google Chrome doesn’t offer the equivalent (only keywords for search engines). Firefox allows to add keywords for any bookmark that you have, but there is no good way to search around for keywords, define them quickly, remove them quickly, etc. qutebrowser comes with a set of commands that serve just this purpose (:quickmark-add, quickmark-del, etc.), apart from adding them very quickly by typing m for quickmarks and M for bookmarks.

Hinting system

You may have tried extensions for other web browsers such as Vimium, Vimperator, or Vimium-FF that let you navigate with Vim shortcuts. They usually use the letter f for following links. Some text appear on the screen for each visible link and you type the letters that match the link you want to see. The best way to get how it works is just to try it out, really.

Well, qutebrowser takes those features and make them even greater! There is, for example, a rapid hinting mode you can access by typing f followed by Ctrl + r and it will open links in the background for as long as you type any matching hint provided as a letter or combination of two letters when there are many visible links on the page. This is especially useful when doing some research to avoid breaking the rhythm on the current reading while preparing more resources to be available.

What’s the best place to start learning about it?

The help page on the website contains all the information you really need. I did stumble upon the following resources, which I would recommend to read in order of appearance:

Quickstart Guide.
[Key bindings cheatsheet](https://raw.githubusercontent.com/qutebrowser/qutebrowser/ma ster/doc/img/cheatsheet-big.png).
FAQ, which is interesting but not indispensable. It did help me take a step forward in trying out qutebrowser though.
Open inside qutebrowser: default keybindings.
Open inside qutebrowser: settings page.
List of commands.

Conclusion

qutebrowser has been around for a while and is very stable. It is ideal for any Vim user and is a great option for anyone interested in efficiency and/or in trying out alternatives. Because I am very fond of relying on the keyboard as much as possible and because I love to program in Python, I have grown to like this web browser very quickly. This is clearly a tool designed for a specific type of user in mind and who knows, you might be one of those.

sglavoie.com – Category: Tools

First Steps with RxJS

Introduction

Basic concepts

Everything is a stream

Operators

Creation

Pipe

Filtering

Time-based

Transformation

Combination

Creating a custom operator

Marble diagrams

Subjects

BehaviorSubject

ReplaySubject

AsyncSubject

Schedulers

Example flow

Reactive testing

Marble testing

Example

Subscribe and assert testing

Example

Tips and tricks

Conclusion

Resources and references

Uncovering some of the merits of text-based diagrams

Introduction

PlantUML: an old love affair

Mermaid: the new muse

When text-based is too clunky

Conclusion

Resources and references

A Guided Tour of an i3 Configuration

Introduction

The Configuration File

i3 config shortcuts

General settings

Screens and monitors

Navigation

Nice addition to make the mouse follow any focused container

Layout

Scratchpad

Borders

dmenu

Shortcuts

Sound

Brightness

Applications

Keyboard & mouse

Colors & theming

Conclusion

More resources and references

My Current Set of Tools and Customizations

Tip the Scales in Times of Instability With the Rock-Solid Debian

Introduction

Why Debian?

Stability and Reliability

Marvelous Package Manager

It Just Won’t Break

Xfce Is Minimalist Enough and Hassle-Free

Xfce vs KDE

Xfce vs GNOME

Xfce vs i3

Xfce vs Other Window Managers

It’s Ideal for Developers

Resources Efficiency & Effectiveness

Rock-Solid Stability (Again, Big Selling Point!)

Packages Availability

Large Community with Freedom in Mind

Resources to Get Started

Conclusion

Suckless: Minimalist Tools That Work Great

What are Suckless tools?

st — Simple Terminal

Configuration

dmenu

Configuration