DEV Community: Paul Akinyemi

Slog: Zero-dependency structured logging in Go

Paul Akinyemi — Sat, 04 Nov 2023 09:37:05 +0000

Structured logging is vital for all production deployments. It’s one of the few windows of insight you have into an app that isn’t running on your local machine. But what makes structured logging different from a call to log.Println(), and why does it matter?

Structured logs conform to a uniform format or share a specific structure, usually consisting of a collection of key-value pairs. The opposite of structured logging is free-form logging, with no consistent layout imposed on the log statements. Here’s an example:



// free form
"Error while running function"

// structured log
"message: 'Error while running function' level:'ERROR' time: '2023-09-17:09:52'"

So why do you need structured logs? Programs find it easier to process structured logs than free-form logs, which is a crucial advantage when you have many statements to comb through while looking for the reason for an error because it lets you perform operations like filtering and searching.

In this article, you’ll learn how to add structured logging to your applications with the slog package, which was added to the standard library in Go 1.21. To follow along, you’ll need:

Go 1.21 or later installed on your machine
A working knowledge of Go

That’s it!

The basics of slog

To begin with slog, you only need to understand three concepts: loggers, records, and handlers. Let’s start with loggers. The logger type is the front end of slog. It's the type that owns the methods you call when you want to log something. When you call one of those methods, the logger creates an instance of another type called a record, whose only job is to store the necessary information to create a log.

Finally, the logger passes the record to an instance of the handler type. The handler type is an interface, and it’s slog’s “backend”. The code that’s responsible for actually creating the log (writing it to stdout, for example) lives in the handler.

To recap, here’s a diagram illustrating the relationship between loggers, records, and handlers:

Let’s look at some code. Assume you’re calling a function that returns an error, and if the error isn’t nil, you want to log it:



err := doSomething()
if err != nil {
    // log the error
}

First, you need a logger. Slog provides a default logger that you can use by calling one of these top-level methods:

slog.Debug()
slog.Info()
slog.Warn()
slog.Error()

These methods all have the same function signature and produce the same output: a log statement whose severity matches the method's name. The Debug method has the lowest severity, and the Error method has the highest. Take a look at the signature of slog.Error():



func Error(msg string, args ...any) {
}

It takes a string as its first argument and then an arbitrary list of key-value pairs. The keys must be strings, but the values can be any type. Calling Error() usually looks like this:



err := doSomething()
if err != nil {
  // log the error
  slog.Error("doSomething returned an error", "error", err)
}

Here, "error" and err form the key-value pair. This code would produce output like this:



2023/09/30 17:41:57 ERROR doSomething returned an error error="random error"

The timestamp was generated automatically by the default logger and is a part of every log record. What happens if you omit the key in the key-value pairs? This code:



slog.Error("doSomething returned an error", err, 5)

Generates this output:



2023/09/30 17:51:32 ERROR doSomething returned an error !BADKEY="random error" !BADKEY=5

Slog will still output the log in a structured, key-value format, but it will prefix all values without a key with a key called !BADKEY, so you must be careful you don’t omit any keys from your key-value pairs.

Slog also offers a more rigid way to create a log that removes the possibility of a !BADKEY error: the Attr type. A value of type Attr represents a single key-value pair, and slog offers you several convenient methods to create an Attr. There’s a method for each basic data type in Go, as well as a slog.Any method that will allow you to use a value of any type to create an Attr. To put this into context, this means that we can replace this method call:



slog.Error("doSomething returned an error", "error", err, 5)

with an Attr version:



slog.Error("doSomething returned an error", slog.String("error", err), slog.Int("id", 5)

The convenience method you should use depends on the type of the value on the key-value pair you want to turn into an Attr. If you stick to Attrs instead of the alternating value style, you’re less likely to omit a key from your log statement. Ultimately, the top-level methods place no restrictions on you - you’re free to use alternating keys and values, Attrs, or to mix both, so it’s up to you to be careful with your log statements.

So far, we’ve focused on the default logger, but if want more control over the output format, you need a create a custom logger. Slog provides the slog.New function for this. slog.New takes a value that satisfies the handler interface and returns a logger that uses the handler you provided to it. Slog provides two types of handlers for you: a text handler and a JSON handler. You can create new loggers like this:



textLogger := slog.New(slog.NewTextHandler(os.Stdout, nil))
// or
jsonLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

The NewTextHandler and NewJSONHandler methods take an io.Writer and a configuration struct as arguments, and return values that satisfy the handler interface. These loggers have the same methods as the default logger, but because they use different handlers, the output they produce is different. Both loggers produce structured, key-value output, but the specific format is different. textLogger will produce a string of regular text, but jsonLogger will produce JSON output. Here’s an example. This code:



textLogger.Error("an error occurred", "error", err)

jsonLogger.Error("an error occurred", "error", err)

Produces this output:



// text handler output
time=2023-10-02T08:12:43.634+01:00 level=ERROR msg="doSomething returned an error" error="random error"

// JSON handler output
{"time":"2023-10-02T08:12:43.634180321+01:00","level":"ERROR","msg":"doSomething returned an error","error":"random error"}

Slog allows you to replace the default package logger with a custom logger. Calling slog.SetDefault(jsonLogger), for example, will cause the top-level methods like slog.Info() to use the jsonLogger instead of the default logger.

Customizing loggers

Slog gives you some options to change the behavior of your loggers. For example, if you have a key-value pair you want to include in all your logs like a user ID, you can use logger.With() to create a new logger that will always include that pair in your log messages. Here’s an example:



authLogger := jsonLogger.With("userId", 1)
authLogger.Error("user action failed", "error", err)
authLogger.Info("user logged in!")

And here’s the output:



{"time":"2023-10-02T11:04:40.852885792+01:00","level":"ERROR","msg":"user action failed","userId":1,"error":"random error"}

{"time":"2023-10-02T11:04:40.852935987+01:00","level":"INFO","msg":"user logged in!","userId":1}

Note how both logs contain the userId:1 pair, even though it wasn’t added to the calls to either Error or Info.

Slog allows you to group key-value pairs using the slog.Group function. This lets you create one value that represents multiple key-value pairs so you can save space when you want to use the group of pairs. To create a group, you need to pass a group name and one or more key-value pairs to slog.Group. Here’s an example:



userInfo := slog.Group("user-info",
  "id", 5,
  "ip-address", "180.80.80.5")

This code creates a group named user-info, with the pairs id:5, ip-address: "180.80.80.5". You can then use the group like this:



jsonLogger.Error("user action failed", userInfo, "error", err)

To get this result:



{"time":"2023-10-02T11:41:31.521075924+01:00","level":"ERROR","msg":"user action failed","user-info":{"id":5,"ip-address":"180.80.80.5"},"error":"random error"}

You can also pass a group as an argument to logger.With :



authLogger := jsonLogger.With(userInfo)
authLogger.Error("user action failed", "error", err)

To get this result:



{"time":"2023-10-02T11:48:10.436603233+01:00","level":"ERROR","msg":"user action failed","user-info":{"id":5,"ip-address":"180.80.80.5"},"error":"random error"}

Finally, you can use the logger.WithGroup() method to prefix all key-value pairs the logger will output with a group name. This is useful in cases where other parts of your codebase might create log statements that have the same keys as the ones you’re using. The prefix allows you to identify which part of the code produced a particular log statement, even when the code uses the same keys. Here’s how it works. This code:



authLogger := jsonLogger.WithGroup("auth")
authLogger.Error("user action failed", "error", err)

Produces this output:



{"time":"2023-10-02T14:42:41.186099512+01:00","level":"ERROR","msg":"user action failed","auth":{"error":"random error"}}

Customizing handlers

Another way to control the output of your log statements is by customizing your handlers. With the handlers slog gives you, that’s done by passing them a HandlerOptions struct. This is the type definition of HandlerOptions:



type HandlerOptions struct {
  AddSource bool
  Level Leveler
  ReplaceAttr func(groups []string, a Attr) Attr
}

A HandlerOptions where AddSource is true will make the log include a source key whose value is the filename, function, and line number from which the log originated. Here’s an example:



jsonLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true}))
jsonLogger.Error("doSomething returned an error", "error", err)

And the output:



{"time":"2023-10-02T15:04:59.905411319+01:00","level":"ERROR","source":{"function":"main.main","file":"/home/Documents/dev/slog-sandbox/main.go","line":21},"msg":"doSomething returned an error","error":"random error"}

A note on enabling AddSource: If you have AddSource enabled and you wrap your log statement in another function, it will cause the location reported by AddSource to be off. Here’s an example:



package main
import (
  "errors"
  "log/slog"
  "os"
)

var logger *slog.Logger
var err error

func wrapper(msg string, err error) {
  logger.Error(msg, err)
}

func main() {
  logger = slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true}))
  err = errors.New("random error")
  wrapper("an error occurred", err)
}

This code returns this output:



{"time":"2023-10-02T17:41:40.031790944+01:00","level":"ERROR","source":{"function":"main.wrapper","file":"/home/Documents/dev/slog-sandbox/main.go","line":13},"msg":"an error occurred","error":"random error"}

And you can see the location of the log is reported as inside wrapper when we want the location where wrapper was called inside main. So what’s the fix? You have to create a record yourself with the correct source information using the runtime package. The documentation provides an example of such a function.

The Level field governs the minimum severity of the logs the Handler will accept. Any log statements with a severity less than the Level field will be ignored by the handler and not logged. But what’s up with the Leveler type? Leveler is an interface with this definition:



type Leveler interface {
  Level() Level
}

And this is the definition of type level:



type Level int

The higher the value of the Level, the more severe it is. The Level field is a Leveler type to allow you to provide a value that can change the Level it returns - you can read about that in the docs, but if you don’t need that, the Level type also satisfies the Leveler interface, so you can pass a static Level instead. Like so:



jsonLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true, Level: slog.Level(4)}))

These are the values for slog’s levels:



const (
  LevelDebug Level = -4
  LevelInfo  Level = 0
  LevelWarn  Level = 4
  LevelError Level = 8
)

Which means that jsonLogger will now log only Warn and Error statements, and ignore Info and Debug. Here's a demonstration:



jsonLogger.Debug("doSomething returned an error", "error", err)
jsonLogger.Info("doSomething returned an error", "error", err)
jsonLogger.Warn("doSomething returned an error", "error", err)
jsonLogger.Error("doSomething returned an error", "error", err)

Will output:



{"time":"2023-10-02T17:21:58.740882837+01:00","level":"WARN","source":{"function":"main.main","file":"/home/Documents/dev/slog-sandbox/main.go","line":23},"msg":"doSomething returned an error","error":"random error"}

{"time":"2023-10-02T17:21:58.740946987+01:00","level":"ERROR","source":{"function":"main.main","file":"/home/Documents/dev/slog-sandbox/main.go","line":24},"msg":"doSomething returned an error","error":"random error"}

We won’t delve into the ReplaceAttr function, but its purpose is to allow you to transform both the keys and values of every key-value pair. You can use ReplaceAttr to remove key-value pairs, change the key names, or modify the value in any way you desire.

Optimizing for performance

If you do a quick Google search, you’ll see the primary culprit for performance issues when logging in Golang is something called allocation. Allocation is the process of reserving computer memory for your program’s use. That memory can be reserved from the stack or the heap. Allocating memory on the stack is straightforward, but allocating memory on the heap is much more complicated, and thus consumes more computational power and time.

So when people say allocations are making a server slower, they mean that executing some log statements is forcing the program to do a lot of heap allocation, and thus slowing it down. Now that you understand what allocation is and why it’s bad for performance, how can you minimize allocations while using slog?

The first thing you should do is use Attrs in all your log statements. Creating an Attr allows your log statement to avoid an allocation when executing for that key-value pair. Taking it one step further, slog provides the Logger.LogAttrs() method. The fact that it accepts only Attrs means that it can avoid allocations even further. According to the documentation,

The call logger.LogAttrs(ctx, slog.LevelInfo, "hello", slog.Int("count", 3))
is the most efficient way to achieve the same output as slog.Info("hello", "count", 3)

logAttrs requires a context as its first argument, which is a value that contains information about the code’s environment that can be passed between functions. Its other arguments are a Level for the log statement, a string, and then an arbitrarily long list of Attrs. You can find a list of other performance considerations in the documentation.

Extending slog

Because slog is split into a front end and a back end, it’s possible to further customize slog while keeping its interface the same, by changing the back end. While slog only provides two built-in handlers, because handler is an interface, you can write a custom implementation to have complete control over the output.

A guide covering how to write custom handlers is out of scope for this post, but you can find one such guide written by the author of slog here. Thankfully, you don’t need to write a handler from scratch to use one. There are several community-contributed handlers, including handlers that allow you to output colored logs, and a handler that lets you implement sampling. You can find a full list here.

Context in slog

Sometimes, handlers may need access to the context of the function where the log statement was called, so slog provides methods that allow you to pass that context as part of the log statement.
The Logger.LogAttr() method takes a context as the first parameter, and all the log statements have alternate versions that let you provide a context. That means that there’s a logger.{Level}Context method for each of slog’s built-in severity levels.

Slog vs Zap vs ZeroLog

To help you decide whether you’d want to use slog in your next project, here’s a table comparing slog to some of the most popular alternatives for structured logging.

	Slog (with built-in handlers)	Zap	ZeroLog
Community and Support	Part of Go’s stdlib	Owned by Uber	No org. backing it
Performance	Slower than Zap	Slower than ZeroLog	Fatest
Extensibility	Most extensible	Decently extensible	Least extensible
Output Format	Plain text or JSON	JSON	JSON or CBOR only

You can find benchmarks for slog, zap, and zeroLog here.

Conclusion

Structured logging is a feature all production applications should have, to provide the developer as much insight into the running of the application as possible. Slog is a new addition to the Golang standard library that provides convenient, efficient, and easily extensible structured logging.

Slog can meet the most common use cases for structured logging with its built-in handlers, but if you need more control or have a niche requirement, it allows you to use third-party handlers, or write your own. I hope you enjoyed the article, and happy coding!

Solving the "session store not found" error while testing handlers in Echo

Paul Akinyemi — Sun, 30 Jul 2023 14:57:27 +0000

Just a quick tip to make the solution for this easier to find. If you're having this problem, you most likely have code similar to this in your test:

e := echo.New()
e.Use(session.Middleware(sessions.NewCookieStore([]byte(sessionKey))))
c := e.NewContext(req, resp)
sess, err := session.Get("user-session", c)

And your call to session.Get() returns the "session store not found" error. Here's what the source code for Get() looks like:

const (
    key = "_session_store"
)

// Get returns a named session.
func Get(name string, c echo.Context) (*sessions.Session, error) {
    s := c.Get(key)
    if s == nil {
        return nil, fmt.Errorf("%q session store not found", key)
    }
    store := s.(sessions.Store)
    return store.Get(c.Request(), name)
}

Your call to Get() throws an error because Get() checks the context you pass to it for the session_store key, but the context returned by e.NewContext() is completely blank, unlike the context echo passes to your handlers when serving HTTP requests.

To solve the error, before you make any calls to Get() you need to set a cookie store on the context returned by e.NewContext() with the key _session_store.

You can do that like this:

e := echo.New()
c := e.NewContext(req, resp)
c.Set("_session_store", sessions.NewCookieStore([]byte(sessionKey)))
sess, err := session.Get("user-session", c)

And that will take care of the error.

How to Integrate FormKit and Bootstrap

Paul Akinyemi — Mon, 16 Jan 2023 11:26:31 +0000

FormKit is powerful, but for the most part, it leaves styling your forms to you. In this article, you'll learn how to style your FormKit forms with Bootstrap.

You’ll discover how to style forms individually, and how you can create an application-wide form theme that is easy to reuse in other projects.

Prerequisites and Assumptions

This guide assumes the following:

You have a working knowledge of FormKit, Bootstrap, and npm.
You understand the Vue 3 Composition API.

Setup

If you want to follow along with this guide, you'll need to do some setup work first.

Installation

Your first task is to create a Vue project with Vite. Start by navigating to the location you want your project to live in the terminal. Next, run the following command in your terminal:

npm create vite@latest

The create-vite command will ask you a few questions. Answer them as shown in the screenshot below:

Then cd into the project folder and install the necessary dependencies:

cd formkit-bootstrap
npm install

Next, start the dev server by running: npm run dev. Visit localhost:5173 to see your application.

Now that you've set up your base Vue project, it's time to install the other dependencies you'll need: FormKit, Bootstrap, and Sass. Open another terminal window and run this code:

npm i bootstrap sass @formkit/vue @formkit/themes @formkit/utils

Your last setup task is to clean up boilerplate you don't need. At this point, your project directory should have a structure that looks like this:

Delete the src/assets folder, src/components/HelloWorld.vue, and src/style.css.

Replace the content of src/App.vue with an empty template and script like so:

<script setup></script>

<template></template>

Next, import all Bootstrap's classes by creating a file called styles.scss in src, with the following content:

// Import all of Bootstrap's CSS
@import "../node_modules/bootstrap/scss/bootstrap";

If you only want to import some of Bootstrap's CSS, you can find the relevant import statements for the parts you want in their docs.

Then import the styling and register Formkit with your Vue app by replacing the content of src/main.js with the following:

import { createApp } from 'vue'
import { plugin, defaultConfig } from '@formkit/vue'
import './styles.scss'
import App from './App.vue'

createApp(App).use(plugin, defaultConfig).mount('#app')

And you're done with the setup.

Styling forms individually

Next, you'll learn how to style individual forms separately.

Start by creating a basic, unstyled login form by adding the following code to the template of src/App.vue:

 <div class="row m-0">
  <FormKit
    type="form"
    submit-label="Log in"
  >
    <h2 class="mb-3"> Log In </h2>

    <FormKit type="email"
             placeholder="john@xyz.com"
             label="Email"
    ></FormKit>

    <FormKit type="password"
             placeholder="***********"
             label="Password"
    ></FormKit>

  </FormKit>
</div>

After that, your Vue application should render a form that looks like this:

So, how will you style this? FormKit provides several methods for styling form inputs, from writing CSS that targets the inputs with attribute values to applying classes to inputs via props.

Before you go on, you need to understand some FormKit jargon: input sections. A section is a specific part of the rendered HTML of a FormKit input. You can find a list and description of the sections for each input in FormKit’s docs for the input.

In general, the outer section refers to an input's outermost wrapper, the input section refers to the core rendered input, and the label section targets the generated label.

The approach to styling you'll use here is to use {section}-class props to apply classes to the form inputs.

Here's what the code for the login form looks like when you style it this way:

<FormKit
    type="form"
    form-class="col-md-4 col-lg-3 mt-5 mx-auto 
                p-5 border rounded"
    :submit-attrs="{
      inputClass: 'btn btn-primary'
    }"
    submit-label="Log in"
  >
    <h2 class="mb-3"> Log In </h2>

    <FormKit type="email"
             placeholder="john@xyz.com"
             outer-class="mb-3"
             input-class="form-control"
             label="Email"
             label-class="form-label"
    ></FormKit>

    <FormKit type="password"
             placeholder="***********"
             outer-class="mb-3"
             input-class="form-control"
             label="Password"
             label-class="form-label"
    ></FormKit>

  </FormKit>

Since you already imported Bootstrap's classes during setup, all you need to style the form is the name of the classes you want to apply to the input.

The code applies classes to sections of each input with {section}-class props that take the name of the class FormKit will apply to that section. In your login form, the outer sections get a class of mb-3, the input sections get form-control, and the label gets form-label.

Here's what the login form should look like after you style it:

And to illustrate how section classes are applied, here's what the rendered HTML for the email input might look like:

That's the general process for styling individual forms: you apply CSS to the input sections, one input at a time.

While this works, it can become tedious and difficult to maintain if you have several forms in your app. It can also become clumsy if your app has large forms.

The solution to this is to create a theme. A theme is a baseline set of styles that FormKit applies to every form in your app.

Creating a Bootstrap theme

Before you build the theme, you'll create a new form to demo how the theme styles forms automatically.

In App.vue, replace the template for the login form with this registration form:

<FormKit
        type="form"
        submit-label="Register"
    >
      <h2 class="mb-3"> Register </h2>

      <FormKit type="text"
               placeholder="John Doe"
               label="Full Name"
      ></FormKit>

      <FormKit type="email"
               placeholder="john@xyz.com"
               label="Email"
      ></FormKit>

      <FormKit type="range"
               label="Age"
               min="0"
               max="100"
               :help="`You are ${age} years old`"
               v-model="age"
      ></FormKit>

      <FormKit type="password"
               placeholder="***********"
               label="Password"
      ></FormKit>

    </FormKit>

Then add this code to the script section:

import {ref} from "vue";

let age = ref(18);

At this point, your registration form should have zero styling, and should look like this:

Next, you'll create your form theme. Add a file to the root of your formkit-bootstrap directory called formkit.config.js, then put the following code in it:

import { generateClasses } from '@formkit/themes'

const config = {
  config: {
    classes: generateClasses({
      global: { // classes
        outer: '$reset mb-3',
        input: 'form-control',
        label: 'form-label',
        help: 'form-text'
      },
      form: {
        form: "col-md-4 col-lg-3 mt-5 mx-auto p-5 border rounded"
      },
      range: {
        input: '$reset form-range',
      },
      submit: {
        outer: '$reset mt-3',
        input: '$reset btn btn-primary'
      }
    })
  }
}

export default config

This code is what's responsible for your theme, so let's break it down. The code relies on the generateClasses function from the @formkit/themes package to apply a list of classes to each section of each input type you specify.

The $reset keyword at the beginning of a class list tells FormKit to disregard any styling applied to that section before that point.

The theme you created is pretty minimal. All it does is apply Bootstrap classes to the inputs you used in your form, and define some default styling for the form container and submit buttons.

Now that you have your theme, the next step is to register it in your app. To do that, replace the code in main.js with this:

import { createApp } from 'vue'
import { plugin, defaultConfig } from '@formkit/vue'
import customConfig from '../formkit.config.js'
import './styles.scss'
import App from './App.vue'


createApp(App).use(plugin, defaultConfig({
  config: customConfig.config
})).mount('#app')

And wait for your dev server to reload.

After your server has reloaded, check your application's page. You should see that your registration form is completely styled, and it should look like this:

If you feel like testing your theme a bit, you can copy the unstyled version of the login form to App.vue to see how the styling applies to it.

Here's a great thing about FormKit’s themes: all they are is a convenient baseline. Applying form-specific styling to an input will override the theme styling without conflicts. This makes it easy for you to tweak the styling of individual forms.

As an example, if you wanted to change the color of the register button to green, you could apply section styles like earlier in the article:

 <FormKit
        type="form"
        submit-label="Register"
        :submit-attrs="{
          inputClass: 'btn btn-success'
        }"
    >

And voila.

Note:
Themes are framework-agnostic. As long as the classes you put in your config are part of your app's stylesheet, you can create a theme with anything from vanilla CSS to Tailwind.

Floating labels

If you want to use floating labels in your forms, you can use a plugin from this GitHub issue. Since Boostrap's floating labels are CSS-only, they won't conflict with Vue or FormKit. Just keep in mind: registering the plugin globally will give all type=text inputs floating labels.

Conclusion

At this point, you've learned how to build your forms with FormKit and style them with Bootstrap, both disparately and by creating a theme. If you need further assistance, FormKit has a Discord server where you can ask for help.

ELI5: Promises in JavaScript

Paul Akinyemi — Sun, 30 Jan 2022 19:44:17 +0000

Intro

Promises are an integral part of asynchronous programming in JavaScript. If you need to do any asynchronous work, chances are you'll need to work with them. But how exactly do Promises work, and how can we use them in our code?

This article explains the basics of Promises in JavaScript, but it does not cover async/await. After you finish reading, you should:

posses an intuitive understanding of how Promises work
understand how to create and use Promises

Prerequisites

This article assumes the reader understands the following concepts:

If you don't already understand those, visit the links above!

What are JavaScript Promises?

A Promise is a JavaScript object that makes it easy for us to write asynchronous code. You can think of a promise as a sort of code IOU. A Promise serves as a placeholder for a value that isn't available yet, and it provides the requested value when said value is available.

JavaScript Promises work much like the non-code kind. When someone makes you a promise, they're saying: I can't do this for you yet, but I'll try my best, then get back to you.

JavaScript Promises are similar. A piece of code requests a resource that isn't available, the same way you might ask for a gift from a friend. In response, the requesting code gets a particular object: a Promise.

This object allows the providing code to deliver the resource when it's ready or notify the requesting code of its failure, the way your friend might come to you later to deliver your gift.

Here's another definition from MDN:

A Promise is an object representing the eventual completion or failure of an asynchronous operation.

Using Promises

I prefer a slightly different phrasing:

A Promise represents an asynchronous operation that will eventually run to completion or encounter an error in the process.

The State of a JavaScript Promise

A Promise can exist in one of three states:

The pending state, where all Promises start.
The fulfilled state, which means the operation is complete.
The rejected state, which means the operation failed.

A Promise exists in the pending state when the operation it represents hasn't run to completion.

A Promise moves to the fulfilled state if the operation it represents runs successfully.

If the operation fails, the Promise moves to the rejected state.

When a Promise moves to either the fulfilled or rejected state, we say that the Promise has "settled".

Creating a Promise

The syntax for creating a Promise is new Promise(function).

The function we pass to the Promise is where the code that will request the desired resource lives. That function has two mandatory arguments: resolve() and reject().

Both arguments are functions that the browser will supply.
We call resolve() in our function when our asynchronous code executes successfully, and we call reject() if we can't complete the operation.

We call the value we pass to resolve() the "fulfilment value", and the value we pass to reject() the "rejection reason".

Here's an example of creating a Promise:


const Promise = new Promise((resolve, reject) => {
// do some async stuff

// if code is successful
resolve(value)

// we couldn't complete the operation for some reason
reject(reason)
})

Using Promises

We can use Promises in two ways:

async/await
Promise instance methods

We won't be covering async/await in this article, but you can read about it here.

Using Promise instance methods

Remember that a Promise is a kind of IOU for the result of an operation? We use Promises by passing the code we want to use the result of that operation (the code that claims the IOU) to one of three instance methods:

then() method
catch() method
finally() method

All instance methods only run after the Promise they belong to have settled, and all instance methods return a new Promise.

The then() method

The then() method accepts up to two functions as arguments.
The first argument contains the code you want to run if the Promise fulfils, and the second contains code that should run if the Promise rejects.

Both arguments to then() are optional. If we don't provide a callback to a then() method corresponding to the parent Promise's current state, the method will return a new Promise in the same state as its parent Promise.

Here's an example:

// we can use then() like this:
demoPromise.then(successCallback, failureCallback)

// or if we don't care about failure:
demoPromise.then(successCallback)
// if demoPromise is in the rejected state,
// the above lcode will immediately return a new rejected Promise


// we can handle only failure like this:
demoPromise.then(undefined, failureCallback)
// if demoPromise is in the fulfilled state,
// this line will immediately return a new fulfilled Promise


// not very useful, but it won't cause an error
demoPromise.then()

The catch() method

The catch() method receives one mandatory argument.
The purpose of the catch() method is to handle the failure of the operation the Promise represents. The argument to catch() contains the code that we want to run if the operation fails.

The calling the catch() method works the same as calling then(undefined, failureCallback).

The function passed to catch receives the rejection reason of the parent Promise as its argument.

The finally() method

The finally() method receives a single function as its argument. The argument to finally() contains code that we want to execute regardless of the success or failure of the operation the Promise represents, and the function passed to finally() never receives an argument.

So now we can use the value represented by a single Promise, but what do we do when we want to execute multiple operations back to back, because the second operation depends on the first? We use Promise Chaining.

Promise Chaining

Promise chaining is a technique where you attach one instance method to another to execute successive operations. Promise chaining is possible because each instance method returns a new settled Promise, which becomes the parent of the following instance method in the chain.

Let's create an example:

const demoPromise = fetch("https://example.com/resource.json")

demoPromise.then((response) => {
// do some cool stuff
return value 1

}).then((response) => {
// first then() returns a new, already settled Promise
// value 1 is the fulfillment value that this then() receives

// we can now do something with value 1
someOperation(value1)
}).catch((err) => {
//handle error if something goes wrong in producing value 1
})

Chained Promise methods usually execute one after another, except when an operation in the chain fails and throws an error.

If this happens, the method that raised the error returns a rejected Promise. The next method to execute is the closest method that has a failure callback (a then() with two arguments or a catch() method).

Execution resumes from the then() method after the method that handled the error, if there is any.

Here's an example of a Promise chain:

const demoPromise = fetch("https://example.com/promise.json")

demoPromise.then((response) => {
// an error occurs
}).then((response) => {
// this function won't run
}).catch((err) => {
//handle error
}).then((err) => {
//resume execution after the error
}).catch((err) => {
// handle any new errors
})

This section covered how to execute successive asynchronous operations, but what if the code we need to run depends on the result of multiple Promises at once?

Using Multiple Promises Together

So what do you do when you want to run code that depends on two or more Promises that need to run simultaneously? We use the static methods of the Promise Class.

The Promise class has six static methods in total, but we'll only talk about the three you're most likely to need:

Promise.all()
Promise.race()
Promise.any()

All static methods take multiple Promises as their argument and return a single Promise based on the settled states of the argument Promises.

Promise.all()

Promise.all() allows you to attach an instance method to a Promise whose fulfilment value is an array of the fulfilment values of the Promises passed to Promise.all().

The Promise the instance method is attached to only moves to the fulfilled state when all Promises passed to Promise.all() have moved to the fulfilled state.
Once this happens, Promise.all() returns a new fulfilled Promise to the instance method.

If any of the input Promises rejects, Promise.all() returns a settled Promise in the rejection state, whose rejection reason is the reason of the first Promise to reject. Any Promises still in the pending state are ignored, regardless of which state they settle into.

Let's look at an example:

const multiPromise = Promise.all(fetch('resource1.json'), fetch('resource2.json'), fetch('resorce3.json'))

multiPromise.then((arrayOfFulfilledValues) => {
// process all the fulfilled values
return value 1
}).catch((err) => {
// process the first rejection that happens
})

Promise.race()

Promise.race() is similar to Promise.all().The difference is: the Promise returned by Promise.race is simply the first Promise to settle. Once any Promise moves to the fulfilled or rejected states, Promise.race() ignores the other input Promises.

const firstSettledPromise = Promise.race(fetch('resource1.json'), fetch('resource2.json'), fetch('resorce3.json'))

firstSettledPromise.then((firstResolvedValue) => {
// process the first fulfilled value
return value 1
}).catch((err) => {
// process the first rejection that happens
// whether in the Promise race or in the then()
})

Promise.any()

Promise.any() is like Promise.race(), but it will wait for the first Promise to move to the fulfilled state, instead of the first Promise to settle.

If an input Promise moves to the rejected state, Promise.any() does nothing as long as other Promises are still in the pending state.

If all the input Promises reject, Promise.any() returns a rejected Promise with an Aggregate Error, containing all the rejection reasons.

const firstFulfilledPromise = Promise.any( fetch('resource1.json'), 
fetch('resource2.json'), fetch('resorce3.json') )

firstFulfilledPromise.then((firstResolvedValue) => {
// process the resolved value
return value 1
}).catch((err) => {
// process the Aggregate error or
// an error that occurs in the then()
})

Use cases of Promises

Typically, working with Promises in the real world involves consuming Promises returned to you from a browser API or JavaScript method.

It's relatively rare that you'll have to create a Promise in your code. Here are some of the most common APIs and functions that return Promises:

The Fetch API
Response.json()

Conclusion

In this article, we covered the basics necessary to work with Promises. If you would like to learn more, visit:

ELI5: Reactivity in Vue 3

Paul Akinyemi — Mon, 17 Jan 2022 18:22:22 +0000

Reactivity. It's a popular buzzword. It's also one of the most convenient features of front-end frameworks.

What is it exactly, and how does it work in Vue 3?

Prerequisites

Working Knowledge of basic JavaScript and JS objects
Working Knowledge of basic Vue.js

What is Reactivity?

Reactivity is a programming paradigm that allows us to adjust to changes in a declarative manner.
Vue 3.x documentation

We say a value is reactive when it can update itself in response to changes in values it depends on. What do we mean by depends on?

Let's take an example:

let val1 = 2
let val2 = 3
let sum = val1 + val2

The value of sum is always determined by the values of val1 and val2, so we say that sum depends on val1 and val2.

What happens to sum when one of the values it depends on changes? In regular JavaScript, it stays the same.

console.log(sum) // 5

val1 = 3

console.log(sum) // Still 5

But if sum was reactive:

console.log(sum) // 5

val1 = 3

console.log(sum) // Sum is 6!

The value of sum would change in response to the change in a value it depended on.

What does Vue need to make a value reactive?

Vue needs to know:

what dependencies that value has.
when those dependencies change.

Vue also needs to be able to re-calculate values when their dependencies change.

How Vue knows when dependencies change

Vue wraps the data object of all components with an ES6 Proxy.
A proxy is an object that wraps a target object.

This is important because all reactive values depend (directly or not) on the properties in a component's data object.

Proxies allow you to intercept all requests to get or set properties of the target. They also let you run any code in response to those requests.

Thanks to this, when code attempts to change one of the properties of a data object, Vue intercepts it and is aware of it.

Vue can then re-calculate any functions that depend on that value. But how does Vue know which functions depend on which values?

How Vue knows which dependencies belong to a value

To make our value reactive, we need to wrap it in a function. Using sum to illustrate again:

// we need to go from

let val1 = 2
let val2 = 3
let sum = val1 + val2

// to

const updateSum = () => {
 sum = val1 + val2
}

Vue then wraps all such functions with an effect. An effect is a function that takes another function as an argument. Vue then calls the effect in place of that function.

When Vue calls an effect, the effect:

Records that it's running.
Calls the function it received as an argument.
Removes itself from the list of running effects after the function ends.

Remember all source values come from a Proxy (the data component)? While executing the function it wraps, the effect will need a property from the data object, and try to read it.

The Proxy will intercept that read request. Vue checks which effect is currently running. It then records that the effect depends on the property it tried to read. This is how Vue knows which values depend on which properties.

So how does Vue know when to re-run the functions that return dependent values?

The answer is once again the magic of Proxies. Proxies can intercept requests to set property values too.

Remember we now have a record of effects, as well as the values they depend on. When the value of a property in data changes, Vue needs to do one thing: check that record and update the source value.

Vue can then re-run all the effects that depend on it, and thus update the values.

Conclusion

This article is a simplified overview of how reactivity works in Vue 3. If you'd like to read more on the subject, here are some resources:

A beginner's guide to writing cleaner code

Paul Akinyemi — Mon, 03 Jan 2022 13:24:14 +0000

Why should anyone even care whether their code is 'clean' or not?

Indeed, the ratio of time spent reading versus writing is well over 10 to 1.
We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.
― Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

I think he put it rather nicely.

So we know why we should care, but what exactly is clean code? What separates clean code from messy code?

This is the answer I prefer: "code is clean when it's easy to read, easy to understand, and it's organized in a way that makes sense to other people".

Now that we have a definition, what exactly can you do to clean up your code? I've outlined my best advice below:

Making your code easy to read

Whitespace is your friend, and too much whitespace is far better than too little

Text, in general, is much easier to read when it's generously spaced, but it tends to feel overwhelming when it's too dense. Dense blocks of text also make it harder to keep track of your position in the document.

To illustrate, here's some dense code:

import function from module
variable = function(argument)
variable = function(variable)
def my_function(argument):
   do xyz
variable = my-function(variable)

And here's some well-spaced code:

import function from module

variable = function(argument)
variable = function(variable)

def my_function(argument):
   do xyz

variable = my-function(variable)

See how some space makes it easier to read?

The length of any line in your code shouldn't exceed 80 characters

Your code will be easier to read in many short lines, instead of a few very long ones. There's nothing magical about the 80 character limit, but I find it a convenient rule of thumb, and anything much longer quickly becomes a pain to read.

Making your code easy to understand

Writing too many comments is much better than writing too few

Comments can sometimes feel bothersome to write, but whenever you write any code that is even slightly complicated, you should have a short comment before it.
The comment should explain what you were trying to achieve and if it's a very complex piece of code, briefly documenting why you chose that approach might be a good idea.

Long identifiers are better than cryptic ones

Sometimes, it feels hard to express the purpose of a variable or a function in one word, and writing a multi-word variable name can feel awkward.
But it's still better to use a long name that clearly explains the purpose of a variable than one that is short but cryptic.

Avoid nesting where you can(but keep line length in mind)

This:

if x and y and z:
   pass

is easier to understand than :

if x:
  if y:
    if z:
      pass

but this:

if black and white and blue and red and green:
      pass

is harder to understand than:

if black and white and blue:
  if red and green:
    pass

Organising your code

As much as is reasonable, DRY(Don't Repeat Yourself)

When you find yourself repeating the same(or very similar) code in more than two different places, you would usually be better served turning it into a function and calling it twice instead. Your code ends up being shorter, and making future changes becomes much less of a hassle.

Side effects are evil, so use with (extreme) caution

Some functions accept parameters and return a value, and do nothing else. That's what an ideal function looks like. Impure functions cause side-effects: changing a global variable or class attribute within the body of the function, for example. Side effects are evil because they generally make debugging a pain in the behind: You end up having to scrutinize each line of code to understand where the heck the value of your variable is coming from.

Your functions should ideally do only one thing

Functions that have more than one job are usually much longer than they should be and tend to cause much confusion in the code you're calling them. To use an analogy, if you asked a friend to grab you a book and he returned with a shoe in his other hand, wouldn't you be really confused? It's the same idea with your functions, so please don't confuse the poor folks who end up using or changing them. Your function should do what its name says, and nothing more.

Summary

Keep it short
Space it out
80-character lines
Write lots of comments
Use good names
D.R.Y
Pure functions
Simple functions

Putting it into practice

No one keeps an eight-step checklist in their head as you're trying to solve a problem or fix a bug, so how does anyone manage to write clean code? Simple. We don't, at least not at first. The answer is called refactoring, and it means changing code without affecting the output.

After you're done with one piece of code, stop. Take ten minutes to breathe. Look away for a little while. Then go over the code you just wrote, and fix any messy bits you find.

Over time, writing clean(er) code will become more and more of a habit, and you'll find progressively fewer mistakes when you refactor.

DEV Community: Paul Akinyemi

Slog: Zero-dependency structured logging in Go

The basics of slog

Customizing loggers

Customizing handlers

Optimizing for performance

Extending slog

Context in slog

Slog vs Zap vs ZeroLog

Conclusion

Solving the "session store not found" error while testing handlers in Echo

How to Integrate FormKit and Bootstrap

Prerequisites and Assumptions

Setup

Installation

Styling forms individually

Creating a Bootstrap theme

Floating labels

Conclusion

ELI5: Promises in JavaScript

Intro

Prerequisites

What are JavaScript Promises?

The State of a JavaScript Promise

Creating a Promise

Using Promises

Using Promise instance methods

The then() method

The catch() method

The finally() method

Promise Chaining

Using Multiple Promises Together

Promise.all()

Promise.race()

Promise.any()

Use cases of Promises

Conclusion

ELI5: Reactivity in Vue 3

Prerequisites

What is Reactivity?

What does Vue need to make a value reactive?

How Vue knows when dependencies change

How Vue knows which dependencies belong to a value

So how does Vue know when to re-run the functions that return dependent values?

Conclusion

A beginner's guide to writing cleaner code

Making your code easy to read

Whitespace is your friend, and too much whitespace is far better than too little

The length of any line in your code shouldn't exceed 80 characters

Making your code easy to understand

Writing too many comments is much better than writing too few

Long identifiers are better than cryptic ones

Avoid nesting where you can(but keep line length in mind)

Organising your code

As much as is reasonable, DRY(Don't Repeat Yourself)

Side effects are evil, so use with (extreme) caution

Your functions should ideally do only one thing

Summary

Putting it into practice

Further Reading