DEV Community: Maxime

Fun with Angular: Create grouped queues of tasks for APP_INITIALIZER

Maxime — Wed, 28 Jun 2023 08:02:19 +0000

Intro

Have you ever heard of APP_INITIALIZER? It's a handy DI token that lets you provide one or more initialization functions that'll be run before your entire app starts. They can come in very handy. But did you know that all the APP_INITIALIZER registered providers will be created at the same time?

Let's make that more flexible.

Because we desperately need it? Hell no.

Because I realized that limitation today and wanted to have some fun? Definitely.

It's a really good example to practice with dependency injection and observables. What else do we need for fun?

APP_INITIALIZER and its limitations

If you want to make sure to execute an initialization function that is blocking before your app starts, APP_INITIALIZER is exactly what you need. Example from the documentation:



function initializeApp(): Promise<any> {
  return new Promise((resolve, reject) => {
    // Do some asynchronous stuff
    resolve();
  });
}

@NgModule({
  imports: [BrowserModule],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: () => initializeApp,
      multi: true,
    },
  ],
})
export class AppModule {}

Pretty cool, right?

But what happens you now have multiple APP_INITIALIZER defined? It's got the multi argument set to true after all so we can provide as many as we want to:



providers: [
  {
    provide: APP_INITIALIZER,
    useFactory: () => initializeApp,
    multi: true,
  },
  {
    provide: APP_INITIALIZER,
    useFactory: () => doSomethingElse,
    multi: true,
  },
  {
    provide: APP_INITIALIZER,
    useFactory: () => wowAnotherThing,
    multi: true,
  },
];

Well they all run in parallel. They'll be called in the order they were declared, but won't wait for each others to finish before executing the next one.

What if we needed (or rather wanted) that? Even better, what if we could define different queues were within a queue, they'd execute one after another but all the queues would be started in parallel:

Talk is cheap. Show me the code

APP_INITIALIZER is an injection token. We want a similar capability. In order to achieve this, we'll do 2 things:

Create an injection token that will be define as multi: true and that we can pass multiple times to build the different tasks of our queues
Create an injection token that will be provided only once as an APP_INITIALIZER and will manage all of our queues. Once all the queues are resolved, only then we'll consider that our initilisation fase for this token is complete

Let's start with the first point.

Defining the token for all of our queues



export type AppInitializerQueueToken = string | symbol | number;

const DEFAULT_QUEUE = 'DEFAULT_QUEUE';

export interface AppInitializerQueueParam {
  queue?: AppInitializerQueueToken;
  task$: Observable<any>;
}

export const APP_INITIALIZER_QUEUE_TOKEN = new InjectionToken<AppInitializerQueueParam[]>(
  `APP_INITIALIZER_QUEUE_TOKEN`,
);

Our APP_INITIALIZER_QUEUE_TOKEN is to be provided multiple times. Hence the array in the type.

If we look at the AppInitializerQueueParam, we see that will be able to define a queue name (could be a string but it could also be a number or a symbol to make sure a queue is really unique). It'll also be able to define a task$ as an observable.

Now let's look at the second point which is the bulk of the work where we'll manage our different queues.

Managing all the queues

We'll start by defining our provider's global shape:



export const APP_INITIALIZER_QUEUE_PROVIDER: Provider = {
  provide: APP_INITIALIZER,
  multi: true,
  useFactory: (appInitializerQueueParams: Nilable<AppInitializerQueueParam[]>) => {
    if (!appInitializerQueueParams) {
      return;
    }

    // @todo

    return () => someObservableHere$;
  },
  deps: [[new Optional(), APP_INITIALIZER_QUEUE_TOKEN]],
};

Already quite a lot going on!

We provide as mentioned earlier, using the APP_INITIALIZER so that this initialisation function is blocking for the app.

We set multi: true because we're using APP_INITIALIZER here and that's how it works, it can be provided multiple times.

We then use a factory function to build our core logic and make sure to type it accordingly with our appInitializerQueueParams.

That params is marked as Nilable (using tsdef), because if we do not provide any APP_INITIALIZER_QUEUE_TOKEN, we'll then get null here. Which leads us to this code:



deps: [[new Optional(), APP_INITIALIZER_QUEUE_TOKEN]],

When we provide the dependencies for our factory function, we say explicitely that providing APP_INITIALIZER_QUEUE_TOKEN is optional. The reason for this is because one could start by definining this queue provider, but not yet have built the queue tokens and we don't want the app to crash for this. Note the use of a tuple here as we cannot use the decorator @Optional as we would normally do when injecting an optional dependency from a class constructor.

Lastly, we do return () => someObservableHere$ because the APP_INITIALIZER expects a function that returns an observable (or it can a promise etc but we'll just focus on observables here).

Create one provider per queue

Remember how we'll have multiple queues, each of them having multiple tasks, and all that provided through DI? Well you have to keep in mind that our code is read line after line:

How tasks are actually provided	How we want our queues to be

This is just one example of the order in which they could be declared. Note that for a given color (queue), all the tasks define the queue order by the order in which they are declared. But it doesn't mean that we have to provide them exactly one after another for the same queue. We could definitely declare tasks from other queues in between.

In order to achieve that transformation from a single array of tasks to a grouped pool of queues with ordered tasks, the first thing we need is to group our providers by queue:



const tasksByQueue = appInitializerQueueParams.reduce((acc, x) => {
  const queueName = x.queue ?? DEFAULT_QUEUE;

  if (!acc[queueName]) {
    acc[queueName] = [];
  }

  acc[queueName].push(x.task$);

  return acc;
}, {} as Record<AppInitializerQueueToken, Array<Observable<any>>>);

Because we want to group by queue, we'll have a data structure that is a Record (a dictionary, an object) that'll take as key a queue identifier (string, symbol or number), and as a value an array of observables, representing all the tasks for the current queue.

Instantiate the providers per queue sequentially

Thanks to RxJS, instantiating all the providers of a queue sequentially is a breathe



const tasksByQueue$ = Object.entries(tasksByQueue).map(([_, tasks]: [string, Array<Observable<any>>]) =>
  concat(...tasks),
);

Note that we don't use Object.values on purpose here as it'd simply cancel all of our previous work to group tasks by queue and put all the tasks into a single array. Instead we use Object.entries to make sure we loop once per queue, and for 1 queue, we concat all the related tasks.

Start all the queues simultaneously

We now have tasksByQueue$ which is Array<Observable<any>> and we want to get instead Observable<any> and make sure that we subscribe to all in paralell:



merge(...tasksByQueue$);

That's it!

Complete code

Usage

Here's an example of how we can then provide our tasks for different queues. Take a look at the console output:

Conclusion

Angular DI system is very powerful and so is RxJS. We've been able to implement a queue system to initialize our app with different tasks ran sequentially, but grouped by queues ran themselves in parallel. The core logic takes ~30 lines of code.

Keep in mind that any initialization attached to APP_INITIALIZER must be carefully through as this will delay the start of your app. While I'm sure there are a few cases where this could come in handy, I mostly thought of that as a little challenge with Angular and RxJS.

I hope you enjoyed this article, if you did let me know with a reaction and eventually drop a comment. It's always nice to hear back from people who took the time to read a post 😄!

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

If you've found a typo, a sentence that could be improved or anything else that should be updated on this blog post, you can access it through a git repository and make a pull request. Instead of posting a comment, please go directly to https://github.com/maxime1992/my-dev.to and open a new pull request with your changes. If you're interested how I manage my dev.to posts through git and CI, read more here.

Follow me

You may also enjoy reading


Build a reactive split-flap display with Angular	How to detect unnecessary renderings of DOM elements in your web app to improve performance

Build a reactive split-flap display with Angular

Maxime — Fri, 09 Jun 2023 08:33:30 +0000

Hello!

I've decided to make a follow up from RxJS: Advanced challenge to build a reactive split-flap display and build UI for it as it's always more pleasant to play around with the final app than emit into a subject to see the text change.

Here's a live demo of what we'll be building, that you can play with 🔥:

If you haven't read the previous article I mentioned above, you should really read it first before jumping on this one as the reactive split-flap logic is already built and we'll only be focusing on the Angular side of things here.

Porting the split-flap code to an Angular service

I'm going to be creating a new Stackblitz where I'll import most of the code we built in the first part and integrate that in a more Angular way.

I'll copy over the entire utils.ts file (except for the part where I was manipulating the DOM manually).

Now, we'll create a new service SplitFlapService that'll reuse our reactive split-flap code and wrap up the creation of new instances:

@Injectable({ providedIn: 'root' })
export class SplitFlapService {
  public getSplitFlapInstance() {
    const input$$ = new Subject<string>();

    const splitFlap$ = input$$.pipe(
      map(inputToBoardLetters),
      switchScan(
        (acc, lettersOnBoard) =>
          combineLatest(
            lettersOnBoard.map((letter, i) =>
              from(getLettersFromTo(acc[i], letter)).pipe(concatMap(letter => of(letter).pipe(delay(150)))),
            ),
          ),
        BASE,
      ),
    );

    return {
      input$$,
      splitFlap$,
    };
  }
}

So far, so good.

Creating the view

First of all, we know we're going to have an input and that our split-flap only support a given number of chars. So we'll start by creating a custom validator for our FormControl that validates the input:

function allowedLettersValidator(): ValidatorFn {
  return (control: FormControl<string>): ValidationErrors | null => {
    const allValidLetters = control.value
      .toUpperCase()
      .split('')
      .every(letter => REVERSE_LOOKUP_LETTERS[letter] !== undefined);

    if (allValidLetters) {
      return null;
    }

    return { invalidLetters: true };
  };
}

Nothing too fancy. We loop on each of the letters in the input and check if they are defined in our allowed chars. If not, we return an object { invalidLetters: true } that'll make the input invalid.

Now, I won't define our split-flap component here. It's only a presentational component which takes an input for all the letters to display and display them. Nothing more so there's little interest in showing that. Feel free to look the code in the Stackblitz in the src/app/split-flap folder.

Finally, we can focus on the component that will use our new service, instanciate a split-flap and use it to show in the view based on an input, the associated split-flap display.

First of all, we inject our service and create an instance of a split-flap:

public splitFlapInstance = inject(SplitFlapService).getSplitFlapInstance();

Then we create a form control for it, with our custom validator:

public fc = new FormControl('', allowedLettersValidator());

Last but not least, we bind the value of our form control to the input$$ of our split-flap (without forgetting to unsubscribe when the component is destroyed):

private subscription: Subscription | null = null;

constructor() {
  this.subscription = this.fc.valueChanges
    .pipe(
      filter(() => this.fc.valid),
      debounceTime(300)
    )
    .subscribe(this.splitFlapInstance.input$$);
}

public ngAfterDestroy() {
  this.subscription?.unsubscribe();
}

Our view can then have the input and the associated split-flap component:

<mat-form-field>
  <mat-label>Input</mat-label>
  <input matInput [formControl]="fc" />
  <mat-error *ngIf="fc.invalid">Invalid chars used</mat-error>
</mat-form-field>

<app-split-flap [letters]="splitFlapInstance.splitFlap$ | async"></app-split-flap>

Here's the final project:

Conclusion

I always like to start thinking about my streams in a really isolated way and once I've got everything working, then integrate where needed. It allows me to make sure I have a reusable code and keep my focus on the core logic, then the view.

Observables integrates of course really well with Angular thanks to a lot of the default API using and the wonderful async pipe.

I hope you enjoyed this article, if you did let me know with a reaction and eventually drop a comment. It's always nice to hear back from people who took the time to read a post 😄! If you gave a go to the challenge yourself, share a link to your Stackblitz or let us know how far you went too!

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


Building scalable robusts and type safe forms with Angular	How to detect unnecessary renderings of DOM elements in your web app to improve performance

RxJS: Advanced challenge to build a reactive split-flap display

Maxime — Fri, 09 Jun 2023 05:02:58 +0000

Hello!

In this article, I'm defining an exercise, challenging you to it, and giving my own answer to it.

I'll explain in details my thinking and little spoiler alert, we'll be using operators that are not used very often!

Time to shut down your imperative programming mind and turn on your reactive one. It'll be an interesting ride.

Intro

If you've been following for me while, you may know by now that I'm a huge RxJS fan. And if you're not yet following me, it's a really good time to chill a bit and click that follow button before we start melting our brains 🧠🔥!

So far on dev.to, I've written 3 articles that are either heavily using or completely dedicated to RxJS:


Brute-forcing an encrypted message from Enigma using the web worker API	Building a reactive microwave for Ryan Cavanaugh with RxJs	RxJS: Avoid an easy mistake when using startWith

This one is by far the most challenging of them all.

Recently, we bought at work a Split flap display, also known as a "Solari board" or "Solari departure board".

youtube.com

The one we got is connected one where we can from an app set the text and it'll update IRL. It's funny to display all kind of important messages or statistics.

I'm sure you know how mesmerizing it can be when all the letters are spinning and suddenly, they all stop, one after another, to display the final sentence. Wouldn't it be a cool challenge to build our own with RxJS?

Rules of the challenge

Before we get started on this, lets define the expected result:

Reactive, reactive, reactive. No imperative programming. Everything should be managed through streams and not rely on external state. Of course it's fine for example to define the allowed letters in a global variable as a constant. But all the internal state of the app should be self contained in the streams
20 letters in total on the display (easy to change anyway)
Can display all the letters from A to Z, can have spaces between letters/words, and numbers from 0 to 9
The page should output the new state of the board whenever one letter is updated
If the text changes at any point in time, whether there's one ongoing already or if it's currently stopped, it shouldn't start from scratch. Just like in reality, it should continue from where it is currently and roll the letters to the new position

Example of an expected output:

Challenging you!

Yes you! I think it'd be a lot of fun if people reading this were to give it a go on their own and share how far they got.

In order to make this easier and not dwell on painful setup, I've created a Stackblitz template ready to go!

It contains some utility functions in utils.ts to manipulate the letters and the DOM, so that we remain focused on the streams.

If you decide to give this a go, fork the original Stackblitz or start from scratch if you prefer to. Feel free to modify anything from the template I've made. It's just here as a base to help, not here to hold you back.

Don't forget to save your Stackblitz and share it as a comment. Even if you didn't manage to go all the way. Let's discuss the results!

My solution

In programming, it's likely that there is more than one solution to achieve the same result. So keep in mind that this is my own approach and someone could come up with a different or even better solution.

From now on, be aware that if you want to work on your own solution first, the following will is one possible answer, so it's really a big spoiler ⚠️.

Without further ado, let's jump straight in.

"Here we gooooooooooooo".

The first thing I try doing when I have to build a feature that relies on observables, is picture in my head how that should all interact. Outter streams, inner streams. While it may be hard to represent visually, I visualise what I'm trying to build as a mix of marble diagrams and pipes that are all connected. I'll do my best to illustrate this but bear with me as this is no easy task.

This is as close as I can represent how things work in a visual way. Now let's dig into the code.

As a reminder, I'm not going to dive into the utils file I've created to manage letters and DOM manipulation. Feel free to take a look here for the whole implementation.

Now, if we focus on the stream itself and put aside the update of the DOM for now, here's the core of our code:

Before we dig into the specifics, let's contemplate for a second the beauty and the power of RxJS.

Keep in mind that the 14 lines of code above are capable of displaying a string just like a split-flap board, with animations (delay applied separately on each letter), keep the current state and if the text changes, start changing the letters from exactly where we are to the new position. It also manages correctly if we try to apply a text and change to a different one while the first one is still running, without resetting from scratch and picking up exactly where it is 🔥. RxJS is truly a thing of beauty.

The first thing we use is our input. It's a simple Subject that we can next into whenever we want. This could be bound to an input text for example.

Then, we map that string to an input that'd match the board letters. Meaning, we want it to be an array of chars. One char for each entry of our display. For example, assuming the board supports 10 chars display for simplicity, if we pass 'HELLO' we'd get back ['H', 'E', 'L', 'L', 'O', '', '', '', '', ''].

Then 🥁... We use a switchScan, which in all honnestly is the first time I could find a use case for it 🎉. As the name suggests, it's a mix of switch and scan:

switch means that we'll stop the inner stream if it's still running when the parent stream emits again
scan is like a reduce. Meaning it take an accumulator, a current value, and the value you return from it becomes the new accumulator. Except that with reduce, it'll wait for the stream to complete before emitting and with scan it'll emit all the intermediate results. Here, switchScan means that our inner stream will be subscribed to, it'll be able to make multiple emissions that will become the new accumulator, and if the parent streams emits again (our input$$ subject), we stop changing the letters and start changing again to reach the new string just provided. Here, this operator is doing a fantastic job, it's the key to being able to stop an animation in the middle of it and continue from where the board is currently without resetting

We then have a combineLatest. In the diagram I drew above, the combineLatest is here to assemble all the streams (1 per letter) that are representend as vertical green arrows.

The build the array of streams that is passed to the combineLatest, we loop on the current letters we just received and for each, we compute all the letters in between what we currently have and the target letter for this tile. We then emit each of these intermediate letters that we'll need to go through by using from.

Finally, with the from emitting all the intermediate letters, we use concatMap with a delay to make sure we emit the intermediate letters in the same order, with a delay in between each for simulate the animation.

Here's the final version live in Stackblitz:

Conclusion

This was a lot to take in, but was an interesting ride. Wasn't it?

Whenever I get the chance to write RxJS code like this, it really reminds me why I love coding. When I found out about reactive programming about 6 years ago, it really blew my mind and I wanted to play with it till I'd be confortable enough to express myself with it, just like most developers are confortable expressing themselves with imperative code that we tend to learn first. Being able to write this now makes me really happy and I try to share that passion for reactive programming whenever possible.

RxJS is a powerful tool and it takes time to learn. But once you manage to wrap your head around it, it's possible to handle really complex use case, in a relatively easy or at least readable way.

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


The holy grail of note-taking: Private data, efficient methodology and P2P encrypted sync across all your devices	Paperless-ngx, manage your documents like never before

The holy grail of note-taking: Private data, efficient methodology and P2P encrypted sync across all your devices

Maxime — Wed, 07 Jun 2023 04:27:56 +0000

Disclaimer

I have learnt very quickly that opiniated articles can get any random stranger with a different opinion to challenge you to death behind his keyboard because you're not enjoying the same things as he does. Therefore I'm going to start this article with a note: This blog post is strongly opiniated. I'm sharing what I like, in case it can be helpful to some. If you've got a different point of view, if you use a different software, if you use a different methodology, don't be offended. Simply share a comment with your opinion explaining why you prefer something different. We don't have to all agree and having multiple feedback will always help others as long as it's constructive. Without further ado, let's get started 🙂!

Intro

Evernote, Microsoft OneNote, Apple Notes, Google Keep, Notion, ... There is a huge number of note-taking apps out there! From dead simple to more sophisticated ones.

One thing the apps I listed above have in common though, isn't to please me: They're in charge of our data. Our notes. While this can surely make our lives easier at first, we often end up writing a lot of precious data in those. If these apps are free, that is for a very good reason: Nowadays, data is gold for tech giants.

But what if I told you there was a non painful way to keep all your notes:

In sync across all your devices
Private
In a standard format, easily exportable

All that quite easily. Which pill do you choose?

When Midjourney makes you choose Morpheus style, you've got enough pills for a lifetime. Won't need another prescription.

Red pill

Welcome to the rabbit hole 🐇.

Note-taking software

I've always been taking notes. Loads of notes. Not super organized, not very thought through, but at least, I had something. About a year ago, I decided it was time to investigate into a better solution as my number of notes started to grow up and it was all becoming a mess.

With data privacy as the key factor, I was looking for a local application, that'd not be in charge of hosting my data and which was using a standard format: Markdown.

After a bunch of research and comparisons, one stood out based on feedback I read: Obsidian. It was time to give it a go.

Obsidian is described as:

The private and flexible note‑taking app that adapts to the way you think.

Here's how it looks (yes they do respect developers, there's a dark theme):

🍒 on the cake, it's been built to be super modular and supports plugins. Because of the huge community, there's nearly 1000 community plugins available when I'm writing those lines. 988 to be exact.

What I like about Obsidian:

Cross platform (including mobile apps)
Beautiful UI
Local
Offline by default
Tags
Graph view to see connections between notes
Community plugins
- Advanced tables. Makes it really easy to manage tables in Markdown without having a mess
- Excalidraw. I've been using Excalidraw since it came out. It was love at first sight. It felt trivial to draw anything I had in mind to illustrate ideas quickly. This integration makes it easy to integrate drawings in notes. While I'm not using it (yet?!), it's worth noting that a few months back, Obsidian added "Canvas" in its core which is similar and maybe more integrated with Obsidian
- Linter. Add a frontmatter with metadata about the creation date of notes and edit date as well
- Navigate cursor history. While coding, having on your mouse the side buttons to go back and forth in your code is fantastic. This plugin gives you 2 arrows in Obsidian to have the same feature if you only have a trackpad
- Prettier format. I prefer to use this instead of the linter mentioned above as Prettier has a huge community and is strongly opiniated
- Reading time. To know how long I'm going to bore you with my articles
- Tag wrangler. To manage existing tags, for example rename them. It detects all the tags in a smart way instead of just doing a string comparison which could affect some text as well if you were to make a global search and replace
- Obsidian Git. I'll talk later on how to sync your notes on different devices but be aware of this plugin that can be useful as well

Whatever OS you're using, just go to the download page and pick the one you want.

Before moving on, I have to say that I have a wish for Obsidian: May it become open source one day. I know the data remains in the users' hands but if Obsidian was to open its code, I feel like it could become a lot stronger than it already is. You can find out more here.

Now that we've got the note-taking software, do we just start creating all of our notes as usual?

Methodology

As mentioned previously, I started to look into note-taking apps alternatives when my number of notes started to grow and it felt messy, hard to find the notes I was looking for.

So I started investigating how to take notes properly. While there are an infinite number of solutions out here, eventually I came across a method called PARA, which stands for:

Project
Area
Resource
Archive

I'll summarise what it's all about but feel free to read this excellent article about it.

The PARA method gives you a way to organise all your notes, into 4 main categories (just folders), which are the ones I listed above.

I've kept the overall idea but renamed a few of them for my notes as it just made more sense to me.

PARA	My folders equivalent
Project	Projects
Area	Areas of responsibility
Resource	Resources
Archive	Archives

Not much difference, but it's just clearer IMO.

I'll give some examples from my own vault to make it clearer where notes should go. I use a lot of sub folders as well in those. It's just important to limit the top level architecture to these 4 folders.

Projects

I've got Art, Domotic, House work and Wood working. Each of these can have sub folders again and as many notes as I want.

This is for ongoing projects. Active ones. Some other examples could be notes for blog posts, YouTube videos you want to create, organising an event, etc.

Areas of responsibility

I've got Car, House work, Professional development.

The name is quite self explanatory. Here are some examples that could go in there: Kids, Health, Taxes, etc.

Resources

I've got Family, Games, House, IT, Medias, Travels.

Some of these folders sounds like they could be in "projects" or "areas of responsibility" but I could have the same folder name in those. Here it's really for notes that are not "projects" or "areas of responsibility" related. General information notes. For examples, I've got "House work" in "Projects" but also "Areas of responsibility" and here "House". In the first one, I put really important house work like renovating the house before for next winter. In the second one, I put some active projects like replacing a few things not working etc. As for here, in resources I put general knowledge like references of different equipments so I don't have to look for them all the time when I need an info, what I think is important to look for if I ever move to another house, etc.

Synchronisation software

We've got our Obsdian app setup, we know how to organise our notes. The last question remaining is how to synchronise our notes across several devices, for example between a laptop, a desktop and a phone.

While this is not the solution I'm going to present, be aware that Obsidian offers its own solution for this, it's called Sync. It's not free, but may be a good way to support the development of Obsidian as well!

Personally, I've been using an open source equivalent of Dropbox that is called Syncthing. I invite you to read on their main page what they offer but essentially it's here for secure data exchange between devices, privately.

Syncthing is available on all the different OS, you can check the download page. If you wish to use it from a server as well, you can install it easily with Docker (either from LinuxServer package or the official one).

Here's how the UI looks (image taken from the official webpage as an example):

On the left, it's all the folders we want to sync
On the top right, "this device" shows several info for the current device (upload/download speed of files, number of files in sync and total weight, etc)
On the bottom right, "Remote devices" shows all the devices you've linked to this one. For example if we're looking at the UI of your desktop, you could see your laptop and your phone here. It shows whether they're online and up to date or not

To add a new device, select "Actions" at the top right, and "Show ID".

It'll show a modal like this one:

Anonymized screenshot, it shows a QR code instead and at the top, some random letters different that xxxxx of course.

You can then either scan the QR code from your phone or if it's another computer, just send the unique ID displayed at the top.

After a few seconds, it'll show you on a modal at the top of syncthing with the ID of the remote device (that you should always double check) and if you accept, the devices will be linked together.

After this, you can select a folder to share:

Like the one containing your Obsidian vault with all your notes for example (or anything else really, could even be a folder to share pictures from your phone in real time when you take them!).

There's then a tab "Sharing" in which you can select which device you want to share this folder with. What's really nice about this is that you can have more than 2 devices in sync for the same folder. Meaning that you can increase the chance of having them always up to date because the sync is done in all the direction whenever the devices are online.

⚠️ Important ⚠️

As noted by bouche_bag on Reddit, Syncthing is here synchronise files across devices but does not replace a backup strategy.

I plan on making an article about Kopia to explain how to make regular backups of your data easily but meanwhile you can look into it yourself if you want. It's definitely not the only solution out there, just an idea. Feel free to compare with other backup softwares.

Conclusion

If you care about data privacy, this could be a solid way to have your notes in sync across several devices without sharing all your data with a big corp. They're also going to be always available, even offline as once the sync is done, your notes are on your device.

As explained, this is how I do things for now, but I'd be delighted to hear more from you and especially which note-taking app is your favourite and why. Who knows, we may all discover the next best app thanks to 1 comment.

Thanks for reading!

I hope you enjoyed this article, if you did let me know with a reaction and eventually drop a comment. It's always nice to hear back from people who took the time to read a post 😄!

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


Next level data privacy with easy, free and secure self hosting at home	How to detect unnecessary renderings of DOM elements in your web app to improve performance

Paperless-ngx, manage your documents like never before

Maxime — Mon, 05 Jun 2023 07:15:30 +0000

Hi there 👋!

In the previous post of this series, we've seen how to setup a server to self host any web application, at home and expose it safely to the web.

In this one, we will be adding our first "real" application: Paperless-ngx.

Paperless-ngx

The description of the project on Github is:

A community-supported supercharged version of paperless: scan, index and archive all your physical documents

I've been using Paperless-ngx for months now and I'm truly impressed that an open source, non commercial project (in any way) can be this good. Start uploading all your documents, add a few tags, correspondents, documents types, start assigning those to the documents you've imported and let the magic happen 🪄. Paperless-ngx will learn from your documents and habits, and then be able to automatically assign tags, correspondents, types, dates etc. The initial phase on which you have to upload and tag all your documents (could be thousands) can be time consuming based on how many you want to triage at first. But once that's done and you enter "routine mode", uploading documents one at a time when you receive them, will take only seconds.

It's 100 times better than saving documents on a Google Drive like service where you organize documents by folder IMO. I was never satisfied with any of the option I had. Organized folders by year? Types? Correspondents? What happens the day you want to search by another criteria? Not a very good experience.

Here are some of the features highlights for Paperless-ngx:

💅 Nice web UI
⚙️ Upload multiple documents and they'll be queued/processed quickly and analysed/indexed
👀 OCR is ran on all the documents, meaning that even if you upload pictures, you'd still be able to search by text
👫 Users and groups permissions. You can have multiple users on the same instance and easily share documents
🔎 Fantastic filtering to find any document quickly. Date range, tags, correspondents, document types, actual content, even though it was a picture thanks to the OCR mode...

Setup in our Docker Compose

The first thing we need to do is to get the service up and running. We'll see how to expose it through swag as a new sub domain right after.

Open up the docker-compose.yaml file we created in the previous blog post and add the following 3 services:

Remember to edit the volumes path if you don't want to save the data in ~/opt folder.



--- # ----------------------------
# ----------------------------
# PAPERLESS-NGX
# Source: https://github.com/paperless-ngx/paperless-ngx/blob/main/docker/compose/docker-compose.mariadb.yml
# to add a user: `docker compose run --rm paperless-ngx-webserver createsuperuser`
paperless-ngx-broker:
  image: docker.io/library/redis:7
  container_name: paperless-ngx-broker
  env_file:
    - common.env
  restart: unless-stopped
  volumes:
    - ~/opt/paperless-ngx/broker:/data

paperless-ngx-db:
  image: docker.io/library/mariadb:10
  container_name: paperless-ngx-db
  restart: unless-stopped
  volumes:
    - ~/opt/paperless-ngx/db:/var/lib/mysql
  env_file:
    - common.env
    - paperless-ngx.database.env
  environment:
    - MARIADB_HOST=paperless
    - MARIADB_DATABASE=paperless
    - MARIADB_USER=paperless

paperless-ngx-webserver:
  image: ghcr.io/paperless-ngx/paperless-ngx:latest
  container_name: paperless-ngx-webserver
  restart: unless-stopped
  depends_on:
    - paperless-ngx-db
    - paperless-ngx-broker
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://localhost:8000']
    interval: 30s
    timeout: 10s
    retries: 5
  volumes:
    - ~/opt/paperless-ngx/webserver/data:/usr/src/paperless/data
    - ~/opt/paperless-ngx/webserver/media:/usr/src/paperless/media
    - ~/opt/paperless-ngx/webserver/export:/usr/src/paperless/export
    - ~/opt/paperless-ngx/webserver/consume:/usr/src/paperless/consume
  env_file:
    - common.env
    - paperless-ngx.database.env
  environment:
    - PAPERLESS_REDIS=redis://paperless-ngx-broker:6379
    - PAPERLESS_DBENGINE=mariadb
    - PAPERLESS_DBHOST=paperless-ngx-db
    - PAPERLESS_DBUSER=paperless
    - PAPERLESS_DBPORT=3306
    - PAPERLESS_URL=https://paperless-ngx.yourdomain.duckdns.org
# ----------------------------

Also remember to edit the PAPERLESS_URL with yourdomain and replace accordingly.

Then create at the same level of the docker-compose.yaml a file called paperless-ngx.database.env with the following content:



MARIADB_ROOT_PASSWORD=GENERATE_STRONG_PASSWORD_1_HERE
MARIADB_PASSWORD=GENERATE_STRONG_PASSWORD_2_HERE
PAPERLESS_DBPASS=PUT_THE_SAME_AS_STRONG_PASSWORD_2_HERE

Let's spin those up!



docker compose up -d

and add a user:



docker compose run --rm paperless-ngx-webserver createsuperuser

It'll prompt you from the command line to enter a few info and then you should end up with this message:



Superuser created successfully.

Time to expose our application to access it.

Expose the service with SWAG and NGINX

Whenever you want to expose a new application, the first thing to do is check if there's a pre-defined templates offered already for us in swag/config/nginx/proxy-confs. Unfortunately, that's not the case for Paperless-ngx. Maybe it'll be added later on!

This is not an issue at all though, because they offer a default template that works straight away in most cases. Copy swag/config/nginx/proxy-confs/_template.subdomain.conf.sample to swag/config/nginx/site-confs and rename it paperless-ngx.conf in the new folder.

Edit it to end up with:



server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name paperless-ngx.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    include /config/nginx/authelia-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        include /config/nginx/authelia-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app paperless-ngx-webserver;
        set $upstream_port 8000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

Note that the line server_name paperless-ngx.*; is the one defining the name of our sub domain which in this case will be paperless-ngx. You can totally change that to whatever you prefer, could be paperless or documents for example. Just remember to update our environment variable PAPERLESS_URL in our docker-compose.yaml accordingly.

Once this file is added, we're pretty much done already! All we've got to do now is to restart SWAG so that it takes it into consideration.

Open up the URL https://paperless-ngx.yourdomain.duckdns.org and 🥁...

This is because we've made sure above to uncomment the 2 lines



# enable for Authelia (requires authelia-location.conf in the location block)
include /config/nginx/authelia-server.conf;

and



# enable for Authelia (requires authelia-server.conf in the server block)
include /config/nginx/authelia-location.conf;

But once we authenticate:

We've got our app running 🎉!

You can now enjoy your Paperless-ngx instance and start uploading your documents! While it uploads and before you start organizing them, I'd definitely recommend to read the best practices guide from the official documentation.

Conclusion

Adding a new service is as simple as finding the Docker Compose configuration, often offered by the project you're trying to run, in their documentation and adding one NGINX config file in SWAG to expose it, safely behind your 2FA security with Authelia.

Happy document triaging!

I hope you enjoyed this article, if you did let me know with a reaction and eventually drop a comment. It's always nice to hear back from people who took the time to read a post 😄!

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


The holy grail of note-taking: Private data, efficient methodology and P2P encrypted sync across all your devices	How to detect unnecessary renderings of DOM elements in your web app to improve performance

How to detect unnecessary renderings of DOM elements in your web app to improve performance

Maxime — Sat, 03 Jun 2023 23:41:49 +0000

The code examples I'm giving is using Angular but it's only a very low amount of code to illustrate the main issue and that issue can happen in any Javascript application that interacts with the DOM.

Intro

Unnecessary repaints in a web app can have a critical impact on performance.

While you may be developing it on a high end device, you may not even notice. But a user running it on a lower end device may definitely.

One question remains: How to be aware of unnecessary repaints?

Illustrate the main issue

Before we dig into this, let me illustrate the original issue.

Here's a very basic app that simulates the fetching of a users array and display each of them, line by line, in a list.

What happens if you click on the "Fetch people" button several times? Apprently nothing. Our list is still the same, nothing is removed, added... And yet...

Finding unnecessary repaints

When we click on the button to fetch people, in this example we emulate a network call'd return an array of people. It'd just happen to be the same result. But behind the scenes, we'd receive a brand new reference for the array... And all the objects in it! Therefore Angular assumes it has to repaint the whole list.

But how to detect this in our entire app? Do we have to be mentally aware of everything that could trigger our framework to repaint unnecessary bits of the app?

There's a very straightforward way to find out, you just have to be aware of a feature in the chrome devtool that is a little bit hidden: Paint flashing.

It can be found in: Dev tools > Hamburger menu > More tools > Rendering > Paint flashing.

Here's where to find it and a demo of what happens with this feature on:

Notice how whenever we fetch the users list, the whole list flashes green? It's the dev tools showing us which DOM elements have been repainted. And if we've got the same list, surely it shouldn't repaint!

Fixing the issue

This will need some investigation and there's unfortunately no silver bullet I can give you here. In this particular case, we can tell Angular to track items by a unique ID to it's aware whether it can reuse an element or not. This blog post isn't about Angular so I won't dwell on the fix but if we use a trackBy on our ngFor like this *ngFor="let person of people; trackBy: trackById" and define the trackById function as



public trackById(_: number, person: Person) {
  return person.id;
}

Then Angular will be able to optimize the rendering.

Notice here that the first time we fetch the list, of course it has to be rendered once. So it flashes green. But whenever I try to fetch it again, only the button flashes (as I'm clicking onto it and it animates).

From there, we know we've optimized our app to avoid unnecessary renderings ✅.

Conclusion

This method will help you find out items that are repainted while they shouldn't, in no time. Of course, the illustration I've made isn't problematic because it's a demo app, but in real life you render hundreds or thousands of DOM elements at an intense pace to reflect fast changes in the data, it could become problematic.

I hope you enjoyed this article. If you're interested in more tips about Angular, RxJS, open source, self hosting, data privacy, and others, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


Brute-forcing an encrypted message from Enigma using the web worker API	Next level data privacy with easy, free and secure self hosting at home

Next level data privacy with easy, free and secure self hosting at home

Maxime — Sat, 03 Jun 2023 00:44:44 +0000

Hello 👋!

Yes you read this well. Self hosting made: Easy. Free. Secure.
With a machine running at your house, not in the cloud. Even if you've never done that before.

That said, if you prefer to apply all this on a server you rent to some provider, it'll work the exact same way. You'll just skip the chapter on the router configuration.

Let's clarify from the start what I mean by:

Easy: The first setup isn't necessarily easy (nor complicated). But it takes a bit of time. We'll go through it all together. Once it's done, adding new apps will take a few seconds or minutes based on how complex the docker strategy is (integrated database or separate container to run Postgres for example)
Free: You will not have to pay monthly or yearly bills for a server you rent online and a domain name because I'll explain how to setup everything locally using your desktop, laptop or a spare computer that you can keep open. You'd still have to pay for a machine if you don't have a spare one, as well as electricity to run it. That said, as a metric for this, my server has consumed ~60kwh in 6 months which makes it ~10kwh/month or ~2€/month.

Intro

Have you ever wished to self host one of the +1000 brilliant open source project listed in awesome-self hosted? A project of your own? A school project? Or anything else that is web based? Sky (or the RAM of your server) is the limit!

If you're afraid of:

🕵️‍♂️ Online solutions that have no respect for your privacy
💸 Online hosting solutions where you're 100% in control of the server and apps, but it can be expensive
🤷‍♂️ How to configure NGINX as it seems too complicated
🛡️ Expose your services safely on the internet

Fear no more! In this blog post we'll be starting from scratch, all the way up to have a local stack safely accessible from the outside of our own network.

What we will achieve

Here's the high level breakdown of what we'll do:

Install and use Docker + Docker Compose in order to have self contained applications
Use DuckDNS to create a free domain name that we can point to our public IP to have access to our apps from outside our home network (note, you could skip this step and use your own domain name of course if you prefer to)
Use SWAG to manage our NGINX server, SSL certificates and fail2ban to ban people trying to brute force our services
Use Authelia (combined to our NGINX in SWAG) to add a double authentication layer in front of all our services
Discuss about how to open up the ports on a router to be able to have access to your apps from the internet
Access the default monitoring dashboard of SWAG from internet, behind our double authentication layer

As a bonus and real life demo I'll soon write another blog post for this serie, where we'll add 3 brilliant applications:

Paperless-ngx to manage all your digital documents
Photoprism to manage all your pictures and videos
Kopia to backup all your data from all the containers

At the end of this blog post, you will:

Be able to have all this stack up and running
Be in a position to add any other web app easily

Let's get started! 🔥
Hang tight for the initial setup. Things will get way easier once this is done.

Architecture overview

As an image is often worth a thousands words, here's the high level overview of what we'll be setting up:

Note that we'll add the 3 apps at the bottom only in the next post of the series.

DuckDNS setup

As mentioned previously, this part is optional and if you prefer to use your domain name instead you can.

Head over DuckDNS website and log in with the provider of your choice. You'll be setup in a matter of seconds. You should land on this page:

Note that the token displayed in the middle of the page must be kept secret, never share it. We'll get back to it soon.

In the domain input, type the domain name you wish to have pointing to your local setup. This will be the base of the public URL to access all your service. Something like https://yourdomain.duckdns.org.

You will only need one as we'll be using sub domains so don't name it for a specific app. For example, with the 3 apps we'll be setting up in the next post, we'll end up with the following URLs:

https://photoprism.yourdomain.duckdns.org
https://paperless.yourdomain.duckdns.org
https://kopia.yourdomain.duckdns.org

From this point, all the commands we run should be run on the machine you decide to use as the server. If you only want to try out this whole stack without having a server, you can definitely give it a go from your current computer as well and migrate the setup to a server if you wish later on. I am running on Ubuntu so all the command will be Ubuntu based. That said it should be quite trivial to change the OS specific commands to match yours.

Docker and Docker Compose setup

I'll assume we start from scratch here. If you have Docker and Docker Compose installed already, you can skip this chapter.

Docker

Run the following:



sudo apt-get update -y

sudo apt-get install -y \
     ca-certificates \
     curl \
     gnupg \
     lsb-release

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update -y

sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Docker Compose



cd ~
mkdir .docker
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Let's make sure we can run Docker without being an admin:

Replace XXXXXXXXXX by your user name.



sudo usermod -a -G docker XXXXXXXXXX
newgrp docker

SWAG setup

If you wish to dig more into SWAG setup, here's the official documentation.

SWAG is no exception to the rule and it'll be ran as a Docker container. We will now create our docker-compose.yaml file that'll let us define all the containers we want to run.

I'd recommend to create a new folder so that all the data from our several containers will be hosted in the same folder, making our lives easier for when we look into Kopia and the backup system. In my case, I've defined it at ~/opt which is a folder I've created myself. If you point to a different folder, make sure to update the paths accordingly in the docker compose file.

Create a file called docker-compose.yaml and paste the following in it:



version: '3.0'

services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    env_file:
      - common.env
      - swag.env
    environment:
      - URL=yourdomain.duckdns.org
      - VALIDATION=duckdns
      - SUBDOMAINS=wildcard
      - DOCKER_MODS=linuxserver/mods:swag-dashboard
    volumes:
      - ~/opt/swag/config:/config
    ports:
      - 443:443
      # https://github.com/linuxserver/docker-mods/tree/swag-dashboard#internal-access-using-server-ip81
      # open port 81 for the dashboard
      - 81:81
    restart: unless-stopped

Make sure to update the URL in the environment. It's the one you've defined in your DuckDNS earlier
Don't forget to change the path for the volume if you've decided to put your files somewhere else than ~/opt. You could just put ./swag/config:/config but then you'd need to make sure to always launch the docker compose from that directory
Feel free to change the ports 443 and 81 if they're already taken to anything you'd like. Remember to only edit the port on the left side of the : as the one on the right is the internal binding for the container

Then create 2 files at the same level:

common.env:



PUID=1000
PGID=1000
TZ=Europe/Paris

To find out your own PUID and PGID, type in your console id and you'll something like this:



$ id
uid=1000(maxime) gid=1000(maxime)

Use these 2 values.

As for the timezone TZ, you can find it here on Wikipedia, in the TZ Identifier column.

swag.env:



DUCKDNSTOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Of course, replace it with the token displayed on your DuckDNS page.

Time to start our first container!



$ docker compose up -d

It should pull the container if you don't have it already and you should see a message like this:



✔ Container swag Started

To make double sure everything went well, we can also check the logs of the container:



$ docker logs swag

You'll see a bunch of logs but the most important line being the last one: Server ready.

Notice as well that a swag folder was created!

Without further ado, let's access the integrated SWAG dashboard... From the internet by configuring our router.

Router configuration

Whether you have your own router or the default "box" provided your internet provider, you will have access to all the settings. That said, each router has it's own UI and I cannot cover all of these. So you will have to search a little bit in your router configuration to find out where you need to access the settings I'll mention. If you don't find them, Google is your friend for this part!

Search in the settings for DHCP. This will let us attribute a local static IP to our computer running SWAG. Create a new rule. It'll ask you what's the device you wish to configure. If it's a little bit smart, it'll list the devices and their IP and you'll be able to select from there. If not, you'll have to enter the current IP and the MAC address of the computer.

Once done, search for NAT & PAT or NAT forwarding or Port forwarding. This will let us bind a port of our public IP and redirect to a given local IP + port. In our case, we will need to have only 1 rule here as we'll be using sub domains to have multiple apps under the same base domain. Create a new rule, for all the protocols (TCP+UDP). Define the external port to be 443. You'll then need to point to a given internal IP and a given port. Specify your computer IP as for the port it'll be 443 as well (or if you changed the 443 port of our docker-compose.yaml file, put the one you wrote here).

As we've passed the environment variable DOCKER_MODS=linuxserver/mods:swag-dashboard, SWAG gives us access to an admin dashboard. Therefore, if everything went well with the router configuration, we should now have access to it from internet! Try to access your domain name with the subdomain dashboard: https://dashboard.yourdomain.duckdns.org

You should see this 🎉:

Feels awesome right?!

You may think though that it's not really a good idea to expose an admin dashboard publicly on the internet. And you'd be right! Let's jump into the next chapter to setup some additional security.

Authelia and double authentication

Authelia is a fantastic piece of open source software which:

Authelia is an open-source authentication and authorization server and portal fulfilling the identity and access management (IAM) role of information security in providing multi-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for common reverse

Essentially, it'll let you put an (extra) authentication layer 🔐 in front of any deployed services 🛡️. You can setup 2 factor authentication (2FA) for reinforced security as well.
🍒 on the cake, you can even define per user access to your apps. To be clear, if an app you deploy has already a login/password access, you can decide to expose it on the internet. But if the security of that app is weak, you may be in troubles. Authelia lets you plug an extra layer with 2FA in front. You'll only have to log once to Authelia and then still log independently to any app that has its own id/password login. Let's crack on!

Add the following service to our docker-compose.yaml file:



# to add a user, add directly to `authelia/users_database.yml`
# then get the encrypted password with
# docker run --rm ghcr.io/authelia/authelia:4.34.6 authelia hash-password yourpassword
# https://www.linuxserver.io/blog/2020-08-26-setting-up-authelia#users_database-yml
authelia:
  image: ghcr.io/authelia/authelia:4.34.6
  container_name: authelia
  env_file:
    - common.env
  volumes:
    - ./authelia:/config
  restart: unless-stopped

Run docker compose up -d so that the Authelia container gets started as well.

You'll see that a new folder authelia will be created with 1 file. But if we look into the logs, we can see that something needs to be fixed before we can actually use Authelia:



$ docker logs authelia

Gives us:



time="2023-06-02T22:34:09+02:00" level=error msg="Configuration: storage: option 'encryption_key' must is required"
time="2023-06-02T22:34:09+02:00" level=fatal msg="Can't continue due to the errors loading the configuration"

This is normal, it's because it's the first time the app is launched and for security reason, we need to change some default values in the config. Let's edit authelia/configuration.yml and replace it with the following:



# https://www.linuxserver.io/blog/2020-08-26-setting-up-authelia

server:
  host: 0.0.0.0
  port: 9091
  read_buffer_size: 4096
  write_buffer_size: 4096
  path: 'authelia'
log:
  level: info
  file_path: /config/logs/authelia.log
jwt_secret: TODO_SOME_RANDOM_SECRET_HERE
default_redirection_url: https://authelia.yourdomain.duckdns.org
totp:
  issuer: authelia.yourdomain.duckdns.org
authentication_backend:
  disable_reset_password: true
  file:
    path: /config/users_database.yml
    password:
      algorithm: argon2id
      iterations: 1
      key_length: 32
      salt_length: 16
      memory: 512
      parallelism: 8
access_control:
  default_policy: deny
  rules:
    - domain:
        - yourdomain.duckdns.org
        - '*.yourdomain.duckdns.org'
      policy: two_factor
      subject:
        - 'user:TODO_YOUR_AUTHELIA_USER_NAME_HERE'
session:
  name: authelia_session
  secret: TODO_SOME_OTHER_RANDOM_SECRET_HERE
  expiration: 1h
  inactivity: 5m
  remember_me_duration: 1M
  domain: yourdomain.duckdns.org
regulation:
  max_retries: 3
  find_time: 2m
  ban_time: 5m
storage:
  encryption_key: TODO_SOME_RANDOM_ENCRYPTION_KEY_HERE
  local:
    path: /config/db.sqlite3
notifier:
  disable_startup_check: false
  filesystem:
    filename: /config/notification.txt

Update all the following:

TODO_SOME_RANDOM_SECRET_HERE
TODO_YOUR_AUTHELIA_USER_NAME_HERE
TODO_SOME_OTHER_RANDOM_SECRET_HERE
yourdomain
TODO_SOME_RANDOM_ENCRYPTION_KEY_HERE

For secrets and encryption keys, generate long and random strings❗

To avoid an error with the container, create an empty file: authelia/logs/authelia.log.

Then do docker compose down && docker compose up -d.
You should see a bunch of new files created in the authelia folder and docker logs authelia shall show a few level=info but no errors ✅.

Last but not least, we need to add a user otherwise it'll be hard to log in!

Launch the following command to encrypt your chosen password for Authelia:



$ docker run --rm authelia/authelia:latest authelia hash-password yourpassword

Change of course yourpassword to a very strong password as this will be your entry point to Authelia. Generating it using a password manager is a good idea.

It'll then print the encrypted password to the console. Keep it there for now and head over authelia/users_database.yml.

Edit this file with the following content:



users:
  your-user-name:
    displayname: 'your-user-name'
    password: 'Put the hashed password generated here starting with $argon2'

Don't forget to change the username (twice) to whatever you want and update the password with the one we just generated.

Now that Authelia is configured, let's expose it through a given subdomain. For this, thanks to all the templates that SWAG has, it's really easy for most apps that we want to add!

In this case, rename swag/config/nginx/proxy-confs/authelia.subdomain.conf.sample to authelia.subdomain.conf.

Restart both services with docker compose down && docker compose up -d then go to https://authelia.yourdomain.duckdns.org and...

VICTORY! 🎉

If you try to log in, you'll get a message saying that you need to activate double authentication to access that resource. And it makes sense as we've specified this as the default in our config! Click on this button:

You'll see a notification:

It's obviously not true because we haven't setup any email provider but Authelia has a clever trick and writes the content instead to authelia/notification.txt. It'll look like this:

Date: 2023-06-02 23:13:28.051443925 +0200 CEST m=+216.364147029
Recipient:
Subject: Register your mobile
Body:
This email has been sent to you in order to validate your identity.
If you did not initiate the process your credentials might have been compromised. You should reset your password and contact an administrator.

To setup your 2FA please visit the following URL: https://authelia.yourdomain.duckdns.org/one-time-password/register?token=some-random-token

Please contact an administrator if you did not initiate the process.

Open up the link that's written and it'll show you a page with a QR code.

With your favourite 2FA authentication app, add it. For example you can use Google Authenticator.

Brilliant! We've got Authelia and 2FA setup 🔥!

But wait, our dashboard at https://dashboard.yourdomain.duckdns.org is still not protected. Let's edit swag/config/nginx/proxy-confs/dashboard.subdomain.conf but first: Note that, usually the proxy-confs contains all the templates and for the apps you want to expose, you rename the file to remove the .sample. In this case the dashboard template is here by default!

Anyway, let's edit dashboard.subdomain.conf. All you have to do for every new .conf file that you use to expose a new service, is to check for the lines with a comment



# enable for Authelia

and uncomment the next line. Make sure you do that on all occurrences of the comment.

There should be at least:

include /config/nginx/authelia-server.conf
include /config/nginx/authelia-location.conf

In this case, there are 5 lines to uncomment ⚠️!

Now reload both services: docker compose down && docker compose up -d and head over your dashboard. It should not be accessible directly and you shall see the Authelia authentication page.

If you get a 403 Forbidden error, you may need to adjust your allowed IP addresses in dashboard.subdomain.conf.

Pro tip 💡: Notice how the URL goes from https://dashboard.yourdomain.duckdns.org to something like https://dashboard.yourdomain.duckdns.org/authelia/?rd=https%3A%2F%2Fdashboard.yourdomain.duckdns.org%2F ?

If you're using a password manager, assuming it's got regex support for URL detection, it's possible to separate your apps from the Authelia login which is very convenient instead of having a domain match that'd just always show you the Authelia entry as the domain doesn't change when Authelia login shows up. It's just the end of the URL.

For your Authelia entry in your password manager, enter this:



https:\/\/([1-9-a-z-]*)\.yourdomain\.duckdns\.org\/authelia

For all your apps, enter this (example with Paperless that we'll setup later):



^https\:\/\/paperless\.yourdomain\.duckdns\.org(?!(/authelia))

This way, when your app doesn't open the Authelia page your password manager will only show 1 entry for the app, and when Authelia shows up it'll only show Authelia, not all of your apps entries.

I believe data privacy is important and being able to self host applications where you own your data is like a super power. In the next post of the series, I'll show how to setup 3 of my favourites open source apps to manage your documents, pictures and backup all that safely.

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

You may also enjoy reading


The holy grail of note-taking: Private data, efficient methodology and P2P encrypted sync across all your devices	Manage your dev.to blog posts from a GIT repo and use continuous deployment to auto publish/update them

RxJS: Avoid an easy mistake when using startWith

Maxime — Fri, 26 May 2023 04:45:00 +0000

As an example in this blog post, I'll use a really basic example with Angular to illustrate a real world example, but we'll focus on RxJS code, not Angular.

startWith can be a really useful operator to make sure an observable emits a value straight away when it gets subscribed to. A good example is when we want to display a form value.

In Angular, we have access to a form value through an observable like this: formControl.valueChanges. Except that this observable only emits when the form value changes. So if we subscribe to it, we won't get notified about the initial value.

In order to have the current form value from the start, we can then do the following:



export class AppComponent {
  public form = new FormControl(null);

  public formValue$ = this.form.valueChanges.pipe(startWith(this.form.value));
}

We can see that so far, it works as expected and the initial null value is the one displayed from the start.

That said, this can lead to sneaky issues.

In the example above, try to change the form value to anything you like. You'll then see that the binding will display the new value live. Then, use the toggle button to hide the value and show it again. It'll display null instead of the real/current form value.

It can be a bit misleading at first why this happens. The reason is because of the startWith. Despite the observable being cold by nature, the startWith function is ran as soon as the class is instantiated. it's just a function, that isn't part of any callback. Initially, the form value is null as we've set it like that. So the first time we subscribe to the observable, it's fine.
Then we unsubscribe from it, in that case with the toggle + the ngIf removing the entire node and the async pipe unsubscribing for us. When we toggle the value again and the ngIf becomes true, we subscribe to the observable again, which as we mentioned had the startWith function ran as soon as the class was created, so it's permanently set to be the initial form value: null.

To go around this, here's what we can do instead:



public formValue$ = concat(
  defer(() => of(this.form.value)),
  this.form.valueChanges
);

Using concat, we say that we'll start our stream with one inner stream, and once it's complete, continue from another one.
The first one is the key here. Using defer, it'll run the defer callback whenever it gets subscribed to, instead of as soon as the class is instantiated with startWith.
It means that whenever we subscribe again to the observable, we'll get the form value at this time, not at the time at which the class was instantiated.

Here's the final code and a live demo:

Do note that this particular case was to have a somewhat realistic example, even though to display the current form value we'd just use form.value and be done with it, without any observable or async pipe. This can be applied anywhere you're using a startWith, from, of to get a value at the time of subscription, not at the time at which the code is read. It can also be useful when a stream can be retried if there's an error.

If you're interested in more articles about Angular, RxJS, open source, self hosting, data privacy, feel free to hit the follow button for more. Thanks for reading!

Found a typo?

Follow me

Stackoverflow: Increase the chances to get answers to your questions

Maxime — Wed, 17 May 2023 04:32:00 +0000

I love Stackoverflow. Probably like a lot of other developers out here. It has helped me thousands of times and saved me countless hours of debugging.

This has lead me to start contributing onto it as well, with the idea that I could give back to the community. I can't say I contribute regularly, but every once in a while I go through topics I like and see if there are some questions I can help on.

While reading a lot of questions, I've noticed that a lot of people don't realise how much quicker they could get an answer by following simple rules. It'd give them a tremendously better views/replies ratio and hopefully let them get the answer they're looking for.

In this blog post, I'm going to share a few tips that may sound obvious for some, but may really help others get answers in general. It's based on my personal feeling and experience using Stackoverflow. I believe most of the following could also apply for example when creating an issue on Github.

The most important tip I'll start with, is also a global summary: Help yourself by making it easy for people to help you. You have to put yourself in the readers' shoes.

Realise that people are reading questions and trying to help you out for free. So if the question is poorly written, chances are, they'll just move on without trying to put much effort into answering. Assume that people will put as much energy answering, than you did when writing the question
When sharing code, never copy paste entire blocks of code directly. Isolate the code with the issue to the best of your knowledge. Then remove everything that isn't essential to your issue. For example if you're sharing some HTML, keep the overall structure, but remove tags, classes, comments that you know are not part of the issue. Even better, create a minimal reproduction highlighting the issue with only what's needed to repro. It takes time. It is not simple. But if you move that burden to the readers, it's unlikely they'll stick around
When possible, create a live reproduction. There are plenty of tools available out here for pretty much all the languages! When it comes to anything relating to Javascript/Typescript, my go to solution is Stackblitz. Blazingly fast, can save projects, fork them, they're easy to share and there's no need to register an account to read or write code by default. Definitely recommend it. But if you're not using Javascript/Typescript, do check for equivalent in your language. Another example I've got in mind is Kotlin. You can use https://play.kotlinlang.org which lets you write, test and share your code easily as well. Find a way for people to play easily with the code you're sharing. It'll help them try solutions on their side and iterate quickly

In conclusion, always ask yourself this question: "If someone who doesn't know anything about my business case was to read this question, would he understand and being able to debug it himself?".

I had no idea Typescript generics were capable of doing that 🤯!

Maxime — Sun, 10 Oct 2021 11:46:18 +0000

Context

An API which we don't own can return an object containing the same property, with a suffix going from 1 to 3. Example:

interface Order {
  // some unique keys
  id: string;
  name: string;

  // some keys "grouped" by 3
  price1: number;
  price2: number;
  price3: number;

  quantity1: number;
  quantity2: number;
  quantity3: number;

  shippingDate1: string;
  shippingDate2: string;
  shippingDate3: string;
}

Notes:

Why is that API not exposing prices, quantities and shippingDates as arrays is beyond the point here. Let's just assume we consume an API that we cannot modify
This is just an example and the returned type could have way more properties like that, so we don't want to have to make the whole remapping manually

The challenge

While the backend may expose it this way for a good reason, in our case, on the frontend side, we'd rather prefer to have a data structure matching our needs in a better way.

Part 1

Build a getGroupedValues function which will have

Input 1: An object
Input 2: A key for one of the repeated properties. Example if we pass an Order as first argument, we could pass as second argument either price, quantity or shippingDate
Output: An array of the type matching the union of all the keys for that common one. Example with Order, if the second argument is price we'd expect as an output number[] but if it's shippingDate we'd expect string[]

This could be a building block to do something like this:

interface OrderRemap {
  id: string;
  name: string;

  prices: number[];
  quantities: number[];
  shippingDates: string[];
}

declare const order: Order; // no need to know where it's coming from for the example

const orderRemap: OrderRemap = {
  id: order.id,
  name: order.name,

  prices: getGroupedValues(order, 'price'),
  quantities: getGroupedValues(order, 'quantity'),
  shippingDates: getGroupedValues(order, 'shippingDate'),
};

Main goal being: Have that function as type safe as possible.

Part 2

Let's try to build a function that'd handle all the following for us:

const orderRemap: OrderRemap = {
  id: order.id,
  name: order.name,

  prices: getGroupedValues(order, 'price'),
  quantities: getGroupedValues(order, 'quantity'),
  shippingDates: getGroupedValues(order, 'shippingDate'),
};

Instead, if the types are defined as such:

interface OrderDetail {
  price: number;
  quantity: number;
  shippingDate: string;
}

interface OrderRemapGrouped {
  id: string;
  name: string;

  orderDetails: OrderDetail[];
}

We'd simply have to do:

declare const order: Order; // no need to know where it's coming from for the example
const orderRemapGrouped: OrderRemapGrouped = groupProperties(order, 'orderDetails');

If you want to give those challenges a go yourself before reading the solutions, now is a good time! You can simply open https://www.typescriptlang.org/play and eventually share the URL of your playground as a comment 😄.

Implementation

Part 1

We know this API will always return those properties, 3 times each (e.g. price1, price2, price3).

So we start here by using a recent feature of Typescript: Template literal types.

type Indices = 1 | 2 | 3;

type GroupedKeys<T> = T extends `${infer U}${Indices}` ? U : never;

Pretty cool how easy it is to extract the base keys of all properties that appears 3 times right?

If we test it out, here's the output:

interface Order {
  id: string;
  name: string;

  price1: number;
  price2: number;
  price3: number;

  quantity1: number;
  quantity2: number;
  quantity3: number;

  shippingDate1: string;
  shippingDate2: string;
  shippingDate3: string;
}

type Indices = 1 | 2 | 3;

type GroupedKeys<T> = T extends `${infer U}${Indices}` ? U : never;

type Result = GroupedKeys<keyof Order>; // "price" | "quantity" | "shippingDate" 🎉

But don't worry, that's not where I was getting at. There's more.

Now let's build our generic getGroupedValues function (not the implementation as it's not the point) but rather its definition:

function getGroupedValues<Obj, BaseKey extends GroupedKeys<keyof Obj>>(object: Obj, baseKey: BaseKey): Array<Obj[`${BaseKey}${Indices}`]> {
  return null as any; // we're not implementing the function, just focusing on its definition
}

It feels like this could be exactly what we want!

We accept any object type, therefore Obj above has no constraint
The base key can be one of grouped keys of that Obj, therefore we write BaseKey extends GroupedKeys<keyof Obj>
We type the inputs (nothing fancy here): object: Obj, baseKey: BaseKey
As for the return type, we know that if we want to get an array of values for the prices (price1, price2, price3) then the baseKey passed as input will be price. Therefore if we access in the object the value of ${BaseKey}${Indices}, we'll get price1 | price2 | price3 which is exactly what we want

Fantastic! All done then! But wait... Typescript doesn't seem to be really happy here. On our return type:

Obj[`${BaseKey}${Indices}`];

It says:

Type '${BaseKey}1 | ${BaseKey}2 | ${BaseKey}3' cannot be used to index type 'Obj'

And it looks legit. We're trying to access properties on a generic which doesn't extends anything (our Obj type).

But how can we keep this function generic and specify that our object will have keys that are composed of the base key and indices 🤔...

Would

Obj extends Record<`${BaseKey}${Indices}`, any>

Work? Surely it can't work, because BaseKey is defined after and itself uses Obj:

Obj extends Record<`${BaseKey}${Indices}`, any>, BaseKey extends GroupedKeys<keyof Obj>

Well this is just fine for Typescript 🤯.

Read this again.

It's fine to say that a given type Obj will be an object (Record) which contains keys of another type (BaseKey), which itself is defined by reading the keys of that Obj.

Me:

I knew that Typescript could handle recursion just fine, like if you define a list which can have a list, which can have a list, ...

interface List {
  propA: number;
  list?: List;
}

const list: List = {
  propA: 1,
  list: {
    propA: 2,
    list: {
      propA: 3,
    },
  },
};

But this? While I think it's amazing, I'm not sure how Typescript manage to settle on the type.

To wrap this up, here's the complete function (without the implementation but with all the types):

function getGroupedValues<Obj extends Record<`${BaseKey}${Indices}`, any>, BaseKey extends GroupedKeys<keyof Obj>>(
  object: Obj,
  baseKey: BaseKey,
): Array<Obj[`${BaseKey}${Indices}`]> {
  return null as any; // we're not implementing the function, just focusing on its definition
}

If we try it out we see the following:

// some mock for an order
const order: Order = {
  id: 'order-1',
  name: 'Order 1',

  price1: 10,
  price2: 20,
  price3: 30,

  quantity1: 100,
  quantity2: 200,
  quantity3: 300,

  shippingDate1: '10 Oct',
  shippingDate2: '11 Oct',
  shippingDate3: '12 Oct',
}

const orderRemap: OrderRemap = {
  id: order.id,
  name: order.name,

  prices: getGroupedValues(order, 'price') // inferred return type: `number[]`
  quantities: getGroupedValues(order, 'quantity') // inferred return type: `number[]`
  shippingDates: getGroupedValues(order, 'shippingDate') // inferred return type: `string[]`
};

I just tried this trick on a Friday afternoon without much hope after being stuck for a while on the error

Type '${BaseKey}1 | ${BaseKey}2 | ${BaseKey}3' cannot be used to index type 'Obj'

I was amazed to see that somehow Typescript is ok with those generics defined at the same level and using each others

Obj extends Record<`${BaseKey}${Indices}`, any>, BaseKey extends GroupedKeys<keyof Obj>

Am I the only one? Did you know about this? Is anyone able to explain how Typescript can be ok with this? In any case leave a comment and tell me what you think about it and if this was useful 😄!

Here's the Typescript Playground link with all the code from above.

Part 2

While creating the API in part 1, we notice that we have to call the getGroupedValues function multiple times, pass a key, recreate the whole object for the remaining properties, etc. It's quite heavy and... Could be simpler!

So now we'll see how to write a function which does all of this for us and groups the different properties based on their index:

const orderRemapGrouped: OrderRemapGrouped = groupProperties(order, 'orderDetails');

So here, orderDetails will be an array containing objects of type {price: number, quantity: number; shippingDate: string} where the values would be coming from the same index. Example for orderDetails[0], it'd have the price, quantity and shippingDate of price1, quantity1 and shippingDate1. Etc.

function groupProperties<Obj extends Record<`${Keys}${Indices}`, any>, Keys extends GroupedKeys<keyof Obj>, NewKey extends string>(
  object: Obj,
  newKey: NewKey,
): Omit<Obj, `${Keys}${Indices}`> & Record<NewKey, Array<{[key in Keys]: Obj[`${key}${Indices}`]}>> {
  return null as any; // we're not implementing the function, just focusing on its definition
}

See some similarities here?

Exactly! The biggest difference being the return type. So let's break it down:

Omit<Obj, `${Keys}${Indices}`>

First, we know that the new object we return should not have any of the properties with the indices (e.g. price1, price2, price3). So we use the built in Omit type to exclude from the common keys concatenated to the indices.

Then:

Record<NewKey, Array<{[key in Keys]: Obj[`${key}${Indices}`]}>>

We add to the return one property, which will have the key passed as second parameter of the function (of type NewKey). That key, will have a value that will be an array of objects.

These objects are going to be all the common keys (price, quantity and shippingDate), associated to the union type of all those properties. For example if we start with price we'll get the union type of price1, price2, price3 which is number as they're all numbers. And same for the others.

Here's the Typescript Playground link with all the code from above.

Conclusion

I didn't think that referencing 2 generics between an object and its keys (part 1) would work. But it does and for the best. The combination of that trick with template literals to extract the common bit of some properties is quite powerful and gives us robust typings on our functions to change a data structure into a fairly different one.

I just love Typescript ❤️✨. If you do as well and you found this article useful, let me know in the comments. I'd also be really interested to see some attempts/solutions from people who gave it a go!

Found a typo?

Follow me

Implement a generic oneOf type with Typescript

Maxime — Mon, 24 Aug 2020 20:36:21 +0000

Have you ever came across a case in your Typescript codebase where you were trying to describe a oneOf?

I did multiple times and previously, I've had to choose between readability and type safety 😑.

Let say we want to express the fact that a player of our game can choose before an adventure an animal to come with him. Not all the animals that are available in the game though, he'd have to choose only 1 between:

a dog 🐶
a wolf 🐺
an eagle 🦅
a mouse 🐭

Readability over type safety

If we care more about readability than type safety, we could simply describe an animal and a player as the following:



interface Animal {
  id: string;
  name: string;

  // the animal can be ONE of the following
  dog: Dog | null;
  wolf: Wolf | null;
  eagle: Eagle | null;
  mouse: Mouse | null;
}

interface Player {
  id: string;
  nickname: string;
  level: number;
  animal: Animal;
}

In this case, the interface would be pretty easy to read, but we could define a dog and a wolf for the player and Typescript would still be happy.

Type safety over readability

We know that the player can only choose between 🐶, 🐺, 🦅 and 🐭. We can take advantage of that information and instead of having a comment // the animal can be ONE of the following, we can express that with Typescript (which will bring us some additional type safety later on!).

To keep things simple, let's start with only 2: 🐶, 🐺.



type Animal = {
  id: string;
  name: string;
} & (
  | {
      dog: Dog | null;
      wolf: null;
    }
  | {
      dog: null;
      wolf: Wolf | null;
    });

interface Player {
  // ... same ...
}

This way we do express the fact that the animal can either be a dog OR a wolf but we can't have both at the same time. While it may seem reasonable to have the type above, let see how it'd look with our 4 animals now:



type Animal = {
  id: string;
  name: string;
} & ({
  dog: Dog | null;
  wolf: null;
  eagle: null;
  mouse: null;
} | {
  dog:  null;
  wolf: Wolf | null;
  eagle: null;
  mouse: null;
} | {
  dog: Dog null;
  wolf: Wolf null;
  eagle: Eagle | null;
  mouse: null;
} | {
  dog: null;
  wolf: null;
  eagle: null;
  mouse: Mouse | null;
});

interface Player {
  // ... same ...
}

Uh 😵... Now can you imagine what it'd look like if we made an update to the game to add 5, 10 or 15 new animals? 🤕

This simply doesn't scale.

Best of both worlds

How cool would it be to have something like the following:



type Animal = {
  id: string;
  name: string;
} & OneOf<{
  dog: Dog;
  wolf: Wolf;
  eagle: Eagle;
  mouse: Mouse;
}>;

interface Player {
  // ... same ...
}

Assuming that we had all the type safety as the example before, I think that'd be pretty nice!

But can we? Let's give it a go, step by step.

The first thing to do would be to have a generic type to which if we pass



{
  dog: Dog;
  wolf: Wolf;
  eagle: Eagle;
  mouse: Mouse;
}

and one key from the type above, let say dog we'd then get the following type:



{
  dog: Dog;
  wolf: Wolf | null;
  eagle: Eagle | null;
  mouse: Mouse | null;
}

We'll call this type OneOnly:



type OneOnly<Obj, Key extends keyof Obj> = { [key in Exclude<keyof Obj, Key>]: null } & Pick<Obj, Key>;

Let's try to breakdown and understand the type above:



type OneOnly<Obj, Key extends keyof Obj>

So far, it should be fine. We can pass a type that we call Obj and we then have to pass one key of that type as the second argument.



{ [key in Exclude<keyof Obj, Key>]: null }

Now, we loop over all the keys of the Obj type, except the one we passed as the second argument of the generic. For all of those keys, we say that the only value they can accept is null.

Last missing piece of the puzzle:



Pick<Obj, Key>

We extract from the Obj type the Key.

So in the end we've got



type OneOnly<Obj, Key extends keyof Obj> = { [key in Exclude<keyof Obj, Key>]: null } & Pick<Obj, Key>;

Which if we use it with a dog for example would give us:



type OnlyDog = OneOnly<
  {
    dog: Dog;
    wolf: Wolf | null;
    eagle: Eagle | null;
    mouse: Mouse | null;
  },
  'dog'
>;

And the OnlyDog type would then be equivalent to:



{
  dog: Dog;
  wolf: Wolf | null;
  eagle: Eagle | null;
  mouse: Mouse | null;
}

Cool! I think we've got the most complicated part of our final OneOf type done ✅.

Now, you may have seen this coming... We've got to loop over our Obj type and generate all the OneOnly types for every key:



type OneOfByKey<T> = { [key in keyof T]: OneOnly<T, key> };

Nothing too fancy here, and yet, this line is pretty powerful! If we do:



type OnlyOneAnimal = OneOfByKey<{
  dog: Dog;
  wolf: Wolf;
  eagle: Eagle;
  mouse: Mouse;
}>;

It'll give us a type like the following:



{
  dog: OneOnly<Dog>;
  wolf: OneOnly<Wolf>;
  eagle: OneOnly<Eagle>;
  mouse: OneOnly<Mouse>;
}

That is suuuuuuper coooool right? But... 🤔

We want a union type of all the values from the type above.

Something like:



OneOnly<Dog> | OneOnly<Wolf> | OneOnly<Eagle> | OneOnly<Mouse>

How can we achieve that? Simply with the following:



type ValueOf<Obj> = Obj[keyof Obj];

This will create a union type of all the values from the Obj type.

So finally, our OneOf is now just:



type OneOfType<T> = ValueOf<OneOfByKey<T>>;

🤩 Nice, isn't it? 🤩

Here's the full code as summary:



type ValueOf<Obj> = Obj[keyof Obj];
type OneOnly<Obj, Key extends keyof Obj> = { [key in Exclude<keyof Obj, Key>]: null } & Pick<Obj, Key>;
type OneOfByKey<Obj> = { [key in keyof Obj]: OneOnly<Obj, key> };
export type OneOfType<Obj> = ValueOf<OneOfByKey<Obj>>;

And how we can now use it:



type Animal = {
  id: string;
  name: string;
} & OneOf<{
  dog: Dog;
  wolf: Wolf;
  eagle: Eagle;
  mouse: Mouse;
}>;

interface Player {
  // ... same ...
}

The cool thing now is, when defining a player and its animal, we can only define one of the animals. Not 0, not 2, not 3, not 4. Only one 😁.

Here's a Typescript Playground which you can have fun with. It contains all the code we've seen and the final demo shown in the gif above.

Found a typo?

Follow me

Building a reactive microwave for Ryan Cavanaugh with RxJs

Maxime — Sun, 19 Apr 2020 12:23:58 +0000

Few weeks ago, I noticed while browsing Twitter that Ryan Cavanaugh had some issues with his microwave :
// Detect dark theme var iframe = document.getElementById('tweet-1245057506662952960-934'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1245057506662952960&theme=dark" }

Let's try to fix it for him, shall we? 😁

Requirements

First, let's define the scope and requirements of our microwave.

As a user, I want my microwave to:

Have 5 buttons so I can interact with it:
- +10s: No matter what the current state is, add 10s to the remaining time
- +60s: No matter what the current state is, add 60s to the remaining time
- Start:
- If the current state is "reset", simply start the microwave
- If the current state is "stopped", resume the microwave
- Stop: If the current state is "started", pause the microwave
- Reset: If the current state is "started" or "stopped", stop the microwave and reset the remaining time to 0
See the remaining time displayed at all time
See the remaining time going down every second when the microwave is started
Automatically stop when it's started and reaches 0s remaining

Pick your weapons

Language

The idea for this app and blog post came from Ryan Cavanaugh's tweet.

Typescript has to be our default 🙏.

Libs

We'll use only 1 library: RxJs.

As you've noticed in the requirements, a microwave is time based and also look like a state machine. RxJs will come really handy to handle such a case 🚀.

State VS streams?

Before we start sketching out our main data flow, I'd like to clarify the difference between the state of our app VS the streams we can use.

A common pitfall I see quite often with RxJs is when someone creates a lot of Subjects or BehaviorSubjects to hold some state. It's making things quite hard to follow and then we have to combine multiple streams to build our main state using for example combineLatest.

While this could work nicely for a few streams, the more streams you add, the hardest it'll be to maintain. A pattern like Redux can instead be used and makes things much simpler to reason about. We'll discover a diagram in the next part to visualize this.

Implementing the main data flow

Before implementing all the "details", we'll think and sketch our main stream. Based on the requirements explained earlier, we know that the state of the microwave will change based on 4 different actions:

Add some time (in our case either +10s or +60s)
Start the microwave
Stop the microwave
Reset the microwave

Let's now transform the above diagram into some code.

Defining the actions

We are now aware that we need to create 4 actions.

Actions are simple objects with:

A type (unique string per action)
A payload (optional and can be anything)

In a very simplified way, we could write them as such:

export interface StartAction {
  type: 'Start';
}

export interface StopAction {
  type: 'Stop';
}

export interface ResetAction {
  type: 'Reset';
}

export interface AddTimeAction {
  type: 'AddTimeMs';
  payload: { timeMs: number };
}

But thanks to Typescript, we can improve that code by building on top of it to make it type safe to:

Create an action before dispatching it
Make sure that in our "reducer" function we do not forget to deal with all of them
Avoid to deal with strings and rather use enums

// as the number of actions has a known length
// I prefer to use an enum to define all of them
// rather than just writing the type of an action
// as a string
export enum EMicrowaveAction {
  START = 'Start',
  STOP = 'Stop',
  RESET = 'Reset',
  ADD_TIME_MS = 'AddTimeMs',
}

export interface StartAction {
  type: EMicrowaveAction.START;
}

export interface StopAction {
  type: EMicrowaveAction.STOP;
}

export interface ResetAction {
  type: EMicrowaveAction.RESET;
}

export interface AddTimeAction {
  type: EMicrowaveAction.ADD_TIME_MS;
  payload: { timeMs: number };
}

// we can also create a union type
// (or a "one of" type) of all our actions
// this will be useful in our reducer later on
export type MicrowaveAction = StartAction | StopAction | ResetAction | AddTimeAction;

// we don't **have to** use the namespace here
// but I personally like this approach as when
// you start having different parts in your
// store, you can use the namespace to clearly
// indicate which one is which, example from
// the previous schema:
// `UserActions`, `MessagesActions`, `DocumentsActions`, etc
export namespace Actions {
  // we then create a function for each action type
  // this allows us to simply call a well named function
  // instead of dispatching an object several times in our app
  export const start = (): StartAction => ({
    type: EMicrowaveAction.START,
  });

  export const stop = (): StopAction => ({
    type: EMicrowaveAction.STOP,
  });

  export const reset = (): ResetAction => ({
    type: EMicrowaveAction.RESET,
  });

  export const addTime = (timeMs: number): AddTimeAction => ({
    type: EMicrowaveAction.ADD_TIME_MS,
    payload: { timeMs },
  });
}

Good! We're now able to send actions 👏.

Let's move on to the part where we need to handle them.

Defining our reducer

Before we define our reducer... What the fork is a reducer?!

Let's take a quick look to our previous diagram:

In the picture above, the reducer is the black square holding the microwave state. As you can notice, every time an action is being dispatched, the reducer will be called.

It is a simple function which:

Takes 2 parameters
- The current state
- The action which just got dispatched
Returns a new state

Important note:

A reducer must be pure:

Data must be immutable Never mutate data from the current state or the action
It must not have any side effect You can't for example make HTTP calls within a reducer. Make them before dispatching an action, and once you've got the result pass it in the payload of the action
For any input passed to the function we must be able to guess the output You can't for example get the current timestamp in a reducer. Instead, if you need the current timestamp get it before dispatching the action and pass it in the payload of the action

The microwave state

We said previously that our microwave will have 4 actions available to change its current state (add time/start/stop/reset). But can the microwave status be the same as all these actions? Is it a 1-1 relationship? No, it isn't. The add time action shouldn't change the current status of the microwave.

Lets define the MicrowaveStatus for that purpose then:

export enum MicrowaveStatus {
  STARTED = 'Started',
  STOPPED = 'Stopped',
  RESET = 'Reset',
}

Now, we need to think about how to hold the internal state of the microwave. What data does our microwave need to work internally?

Of course, it'll need the status we just created so we can start with:

// internal state to the reducer
interface MicrowaveInternalState {
  status: MicrowaveStatus;
  // ... todo
}

It'll also need to keep track of how much time the user plans to use it (when adding time through the add time action):

interface MicrowaveInternalState {
  status: MicrowaveStatus;
  timePlannedMs: number;
  // ... todo
}

And finally, we need to keep track of how much time has been spent already with the microwave in the STARTED status.

interface MicrowaveInternalState {
  status: MicrowaveStatus;
  timePlannedMs: number;
  onAndOffTimes: number[];
}

You may now think:

Why is onAndOffTimes an array of numbers instead of just the time elapsed in the STARTED status?

Lets think a bit about how a microwave works:

You enter some time using the buttons
You press start
The microwave is running
You can pause/restart the program until you reach 0s left (or stop it before)

At no point in that workflow you press a button to keep the microwave running every second. Well, this is exactly the same for our actions.

Actions represent how we want to interact with the state and every computation should be driven from the state downstream.

In this case, we keep a record of the timestamps when the user toggle the microwave on and off. Later on, we'll see how to compute the elapsed time. In the meantime, we can still prepare the interface that will be consumed publicly when we subscribe to the microwave stream. It is pretty much the same except that instead of onAndOffTimes: number[] we'll have timeDoneMs: number.

// exposed/computed state
export interface MicrowaveState {
  status: MicrowaveStatus;
  timePlannedMs: number;
  timeDoneMs: number;
}

Here's another diagram to visually represent what we're building:

Implementing the reducer function

Now that we've understood the architecture we're trying to build and especially the role of the reducer function, we can start implementing it.

If you refer to the previous diagram, the reducer is a (pure) function which takes 2 parameters: The MicrowaveInternalState and an action. We'll see later on how to attach the current timestamp to each action (without having to pass it manually all the time). For now, we'll assume the current timestamp is passed within an object, next to the current action.

const microwaveReducer = (microwave: MicrowaveInternalState, { value: action, timestamp }): MicrowaveInternalState => {
  switch (action.type) {
    case EMicrowaveAction.START:
      return {
        // todo: return the new `MicrowaveInternalState`
      };

    case EMicrowaveAction.STOP:
      return {
        // todo: return the new `MicrowaveInternalState`
      };

    case EMicrowaveAction.RESET:
      return {
        // todo: return the new `MicrowaveInternalState`
      };

    case EMicrowaveAction.ADD_TIME_MS: {
      return {
        // todo: return the new `MicrowaveInternalState`
      };
    }

    default:
      unreachableCaseWrap(action);
  }

  return microwave;
};

Before we start implementing each case, note the use of a switch statement and the call in the default of unreachableCaseWrap.

As the action.type is a union type, every time we handle one case and return a result (hence stopping the switch), Typescript is smart enough to narrow down the next possible type. By having an unreachableCaseWrap function to which we pass the action.type, we can ensure that we don't forget to implement any type in our switch 🔥! Otherwise Typescript would throw an error at compile time.

export const unreachableCaseWrap = (value: never) => {};

By saying that unreachableCaseWrap takes as an input a value of type never, if within our switch statement we're not handling all the different possible types, Typescript will notice that we're trying to pass a value which is not of type never.

Cool! Now let's move on to implementing our reducer. Remember, we have to return a new state, without mutating the previous one. We want this function to remain pure.

Does this mean we've got to deep copy the whole state? Isn't that going to be really expensive?

Nop 😁! And thanks to ES6 we can easily do this using the spread operator. Here's a tiny example:

const obj1 = {
  propA: {
    propA1: 'Value A 1',
    propA2: 'Value A 2',
  },
  propB: {
    propB1: 'Value B 1',
    propB2: 'Value B 2',
  },
};

console.log(obj1);
// displays:
// ---------
// {
//   propA: {
//     propA1: 'Value A 1',
//     propA2: 'Value A 2',
//   },
//   propB: {
//     propB1: 'Value B 1',
//     propB2: 'Value B 2',
//   }
// }

const obj1Updated = {
  ...obj1,
  propB: {
    ...obj1.propB,
    propB2: 'NEW VALUE',
  },
};

// `obj1` has **not** been modified
console.log(obj1);
// displays:
// ---------
// {
//   propA: {
//     propA1: 'Value A 1',
//     propA2: 'Value A 2',
//   },
//   propB: {
//     propB1: 'Value B 1',
//     propB2: 'Value B 2',
//   }
// }

console.log(obj1Updated);
// displays:
// ---------
// {
//   propA: {
//     propA1: 'Value A 1',
//     propA2: 'Value A 2',
//   },
//   propB: {
//     propB1: 'Value B 1',
//     propB2: 'NEW VALUE',
//   }
// }

And we can use the same syntax for arrays. Instead of using methods which mutates the array, like push for example, we can do the following:

const arr = [1, 2, 3];

console.log(arr);
// [1, 2, 3]

const arrUpdated = [...arr, 4];

// `arr` has **not** been modified
console.log(arr);
// [1, 2, 3]

console.log(arrUpdated);
// [1, 2, 3, 4]

As we're not deeply copying our entire state, this kind of copy is as efficient as possible. We reuse all the objects that we're not modifying and instead of making a deep copy, we just pass their reference.

Now that we know how to create an updated version of an object without mutating it, lets take a look to the full reducer:

const microwaveReducer = (microwave: MicrowaveInternalState, { value: action, timestamp }): MicrowaveInternalState => {
  switch (action.type) {
    case EMicrowaveAction.START:
      return {
        ...microwave,
        status: MicrowaveStatus.STARTED,
        onAndOffTimes: [...microwave.onAndOffTimes, timestamp],
      };

    case EMicrowaveAction.STOP:
      return {
        ...microwave,
        status: MicrowaveStatus.STOPPED,
        onAndOffTimes:
          microwave.status !== MicrowaveStatus.STARTED
            ? microwave.onAndOffTimes
            : [...microwave.onAndOffTimes, timestamp],
      };

    case EMicrowaveAction.RESET:
      return INITIAL_MICROWAVE_STATE;

    case EMicrowaveAction.ADD_TIME_MS: {
      return {
        ...microwave,
        timePlannedMs: microwave.timePlannedMs + action.payload.timeMs,
      };
    }

    default:
      unreachableCaseWrap(action);
  }

  return microwave;
};

Once again, our function is pure 🙌. Easy to understand, not a single side effect, for any input we're able to expect a given output and easily testable. Fantastic!

Implementing the selector function

As a reminder, here's how the selector should look like:

Just like a reducer, a selector must be a pure function.

const microwaveSelector = (microwave: MicrowaveInternalState): MicrowaveState => {
  switch (microwave.status) {
    case MicrowaveStatus.RESET:
      return {
        timePlannedMs: microwave.timePlannedMs,
        status: MicrowaveStatus.RESET,
        timeDoneMs: 0,
      };

    case MicrowaveStatus.STOPPED: {
      const timeDoneMs = computeTimeDoneMs(microwave.onAndOffTimes);

      if (microwave.timePlannedMs === 0 || microwave.timePlannedMs - timeDoneMs <= 0) {
        return {
          timePlannedMs: 0,
          status: MicrowaveStatus.RESET,
          timeDoneMs: 0,
        };
      }

      return {
        timePlannedMs: microwave.timePlannedMs,
        status: MicrowaveStatus.STOPPED,
        timeDoneMs: timeDoneMs,
      };
    }

    case MicrowaveStatus.STARTED:
      return {
        timePlannedMs: microwave.timePlannedMs,
        status: MicrowaveStatus.STARTED,
        timeDoneMs: computeTimeDoneMs(microwave.onAndOffTimes),
      };

    default:
      throw new UnreachableCase(microwave.status);
  }
};

We don't really care about the computeTimeDoneMs. It gives us how much time did the microwave spent running from the onAndOffTimes array. As it's not what we want to focus on today, here's the code without further explanations:

export const chunk = <T>(arr: T[]): T[][] =>
  arr.reduce<T[][]>((result, _, index, array) => {
    if (index % 2 === 0) {
      result.push(array.slice(index, index + 2));
    }
    return result;
  }, []);

const computeTimeDoneMs = (onAndOffTimes: number[]) =>
  chunk(onAndOffTimes).reduce((timeElapsed, [on, off]) => timeElapsed + off - on, 0);

Create the microwave state stream

Build the MicrowaveInternalState stream

We now have all the logic for our state and our selector. We can start working on our data flow using RxJs streams. For that, we'll start by creating a factory function which for a given action$ observable, will return a MicrowaveState observable.

As a first step, we'll create the function and manage the MicrowaveInternalState using our reducer:

const INITIAL_MICROWAVE_STATE: MicrowaveInternalState = {
  timePlannedMs: 0,
  onAndOffTimes: [],
  status: MicrowaveStatus.RESET,
};

export const createMicrowave = (action$: Observable<MicrowaveAction>): MicrowaveState => {
  const microwaveState$: Observable<MicrowaveInternalState> = action$.pipe(
    timestamp(),
    scan(microwaveReducer, INITIAL_MICROWAVE_STATE),
    startWith(INITIAL_MICROWAVE_STATE),
  );

  // todo: use our selector to transform the `MicrowaveInternalState` into a `MicrowaveState`
  // ...
};

In less than 5 lines, we've got a fully reactive approach to manage our internal state so far 🤯.

This is one of the reasons why RxJs is powerful and worth learning. But as nice as this is, it's probably a lot to process already! Lets go through it together:

We get an action$ stream. Any time a new action is dispatched, we'll receive it here
The timestamp operator wraps a value into an object containing the value + the current timestamp
The scan operator is similar to the reduce function available on iterable objects in Javascript. You provide a function (our microwaveReducer in this case), which will get an accumulator (our MicrowaveInternalState) and a value (our action). From this, it should return a value which will be emitted downstream and which will also become the new value passed as the accumulator the next time the scan runs. Finally, as the 2nd argument of the scan operator, we provide an initial state (in our case, the INITIAL_MICROWAVE_STATE). The scan operator is really powerful and let us have the state scoped to that function. It's not created before and it is only possible to update it by sending a new value to the scan. No one has access to a variable holding our state and likely to be mutated
Last but not least, when we subscribe to the microwave we expect to receive an initial state. Before you start your microwave, it still exists, doesn't it? So right after the scan, we emit the initial state of the microwave. Another possible way to achieve this would be to startWith(Actions.reset()) before the scan and then the scan would be started with the RESET action. But why run the whole reducer function when we know the initial value it's about to return?

Build the public MicrowaveState stream using our selector

So far we know the current state of the microwave, how much time is left, and we've got an array with the timestamps of when it was toggled STARTED/STOPPED.

How can we get an update every second to represent the state of the microwave while it's running (started)?

const microwave$: Observable<MicrowaveState> = microwaveState$.pipe(
  switchMap(microwave => {
    switch (microwave.status) {
      case MicrowaveStatus.RESET:
      case MicrowaveStatus.STOPPED:
        return of(microwaveSelector(microwave));

      case MicrowaveStatus.STARTED:
        return timer(0, 1000).pipe(
          timestamp(),
          map(({ timestamp }) =>
            microwaveSelector({
              ...microwave,
              onAndOffTimes: [...microwave.onAndOffTimes, timestamp],
            }),
          ),
          takeWhile(x => x.timeDoneMs < x.timePlannedMs),
          endWith(MICROWAVE_RESET_STATE),
        );

      default:
        throw new UnreachableCase(microwave.status);
    }
  }),
);

For MicrowaveStatus.RESET and MicrowaveStatus.STOPPED, we just pass the MicrowaveInternalState to our selector which will transform it to a MicrowaveState.

For the MicrowaveStatus.STARTED, it's slightly different as we need to update the stream every second (for the countdown):

timer(0, 1000): Start the stream immediately and emit every seconds
timestamp: Get the current timestamp (which will be updated every second thanks to timer)
map: Use the microwaveSelector (just like MicrowaveStatus.RESET and MicrowaveStatus.STOPPED) but instead of passing the internal state directly, we create a new object (immutability for the win!). Within that new object, we add the current timestamp into the onAndOffTimes (which therefore will update the timeDoneMs in the output) 🙌. The important thing to understand here is that thanks to immutability we never modify the original onAndOffTimes so by adding the new timestamp in the array we don't accumulate them in the array. We take the initial one and add one. We take the initial one and add one. We take the initial one and add one. Etc...
takeWhile(x => x.timeDoneMs < x.timePlannedMs): As soon as the time done is equal or greater than the time planned, we stop that inner stream (no more update needed every second)
endWith(MICROWAVE_RESET_STATE): When the stream ends, we emit the reset state

Note that before that inner stream, we've got:

microwaveState$.pipe(
  switchMap(microwave => {
    // ...
  }),
);

So when microwaveState$ emits new value, we'll kill all that inner stream and start a new one, which is exactly what we want.

Final version of the microwave factory function

export const createMicrowave = (action$: Observable<MicrowaveAction>): Microwave => {
  const microwaveState$: ConnectableObservable<MicrowaveInternalState> = action$.pipe(
    timestamp(),
    scan(microwaveReducer, INITIAL_MICROWAVE_STATE),
    startWith(INITIAL_MICROWAVE_STATE),
    publishReplay(1),
  ) as ConnectableObservable<MicrowaveInternalState>;

  const microwave$: Observable<MicrowaveState> = microwaveState$.pipe(
    switchMap(microwave => {
      switch (microwave.status) {
        case MicrowaveStatus.RESET:
        case MicrowaveStatus.STOPPED:
          return of(microwaveSelector(microwave));

        case MicrowaveStatus.STARTED:
          return timer(0, 1000).pipe(
            timestamp(),
            map(({ timestamp }) =>
              microwaveSelector({
                ...microwave,
                onAndOffTimes: [...microwave.onAndOffTimes, timestamp],
              }),
            ),
            takeWhile(x => x.timeDoneMs < x.timePlannedMs),
            endWith(MICROWAVE_RESET_STATE),
          );

        default:
          throw new UnreachableCase(microwave.status);
      }
    }),
    shareReplay({ bufferSize: 1, refCount: true }),
  );

  // we need to keep the state subscribed as if no one is listening
  // to it we should still be able to take actions into account
  // note: we don't unnecessarily subscribe to `microwave$` as this
  // does some computation derived from the state so if someone subscribes
  // later on, that stream would still be up to date!
  const microwaveStateSubscription = microwaveState$.connect();

  return {
    microwave$,
    cleanUp: () => {
      microwaveStateSubscription.unsubscribe();
    },
  };
};

Notice the subtle changes above?

publishReplay(1)?
shareReplay({ bufferSize: 1, refCount: true })?
microwaveState$.connect()?
cleanUp?

This is the last part 🥵. Hang tight!

We have 2 stream to represent:

The internal state: microwaveState$
The public state: microwave$

When someone calls the createMicrowave factory function, they'll get a stream representing the microwave. But what if they start dispatching actions without listening to the microwave first? Nothing would be taken into account which is unfortunate.

To fix this, we put publishReplay(1) at the end of microwaveState$. This operator is quite powerful and brings the following features:

The "publish" side transforms the Observable into a ConnectableObservable. It means that we will have to connect manually to the observable. The connect method will basically subscribe to it. This is why we need to return an object containing a cleanUp which will unsubscribe to it when needed
The "replay" side (which needs an argument, here 1) means that if a value is emitted by that stream before someone subscribe to it downstream, it'll keep the value and send it straight away to a late subscriber

The last one to understand is shareReplay({ bufferSize: 1, refCount: true }). It's applied as the last operator of the microwave$ stream. When someone calls the createMicrowave factory function and subscribe multiple times to the microwave$ stream, the microwaveState$ won't be re-triggered (as explained previously it's been shared), but for microwave$ we'd have the whole selector and observable chain for the started state running 1 time per subscriber. When we create an instance of a microwave using the createMicrowave, we should be able to subscribe multiple times to it without triggering that logic multiple times. Therefore, we use shareReplay. We set the bufferSize property to 1 so that if someone subscribes later on, he'll get the last value straight away. We set the refCount property to true (which is very important), so that if the microwave is started but no one listen, the whole observable chain with timer, timestamp, microwaveSelector, takeWhile, endWith will NOT run. Only if there's at least one subscriber. And if more than one, they share the results 🔥.

Conclusion

On one hand, working with observables and thinking reactively can be very challenging. There's a steep learning curve and the concept is very different from imperative programming.

On the other hand, RxJs is very powerful and once we get used to it, it becomes easier to write complicated workflows.

If you decide to use reactive programming, remember that using subscribe is where the reactive programming ends.

// Detect dark theme var iframe = document.getElementById('tweet-1180316203937681410-672'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1180316203937681410&theme=dark" }

Found a typo?

Follow me

DEV Community: Maxime

Fun with Angular: Create grouped queues of tasks for APP_INITIALIZER

Intro

APP_INITIALIZER and its limitations

Talk is cheap. Show me the code

Defining the token for all of our queues

Managing all the queues

Create one provider per queue

Instantiate the providers per queue sequentially

Start all the queues simultaneously

Complete code

Usage

Conclusion

Found a typo?

Follow me

You may also enjoy reading

Build a reactive split-flap display with Angular

Porting the split-flap code to an Angular service

Creating the view

Conclusion

Found a typo?

Follow me

You may also enjoy reading

RxJS: Advanced challenge to build a reactive split-flap display

Intro

Rules of the challenge

Challenging you!

My solution

Conclusion

Found a typo?

Follow me

You may also enjoy reading

The holy grail of note-taking: Private data, efficient methodology and P2P encrypted sync across all your devices

Disclaimer

Intro

Red pill

Note-taking software

Methodology

Projects

Areas of responsibility

Resources

Archives

Synchronisation software

Conclusion

Found a typo?

Follow me

You may also enjoy reading

Paperless-ngx, manage your documents like never before

Paperless-ngx

Setup in our Docker Compose

Expose the service with SWAG and NGINX

Conclusion

Found a typo?

Follow me

You may also enjoy reading

How to detect unnecessary renderings of DOM elements in your web app to improve performance

Intro

Illustrate the main issue

Finding unnecessary repaints

Fixing the issue

Conclusion

Found a typo?

Follow me

You may also enjoy reading

Next level data privacy with easy, free and secure self hosting at home

Intro

What we will achieve

Architecture overview

DuckDNS setup

Docker and Docker Compose setup

Docker

Docker Compose

SWAG setup

Router configuration

Authelia and double authentication

Found a typo?

Follow me

You may also enjoy reading

RxJS: Avoid an easy mistake when using startWith

Found a typo?