DEV Community: Taha Shashtari

Make your JavaScript more readable with named parameters

Taha Shashtari — Mon, 27 Jan 2025 12:11:59 +0000

We write and use functions all the time in JavaScript—whether you write FP or OOP. Every time you call a function, you need to know which arguments to pass and in what order.

The position of the arguments doesn't show what they are for. Take a look at this example:

addToCard(456, 2, { color: 'blue', size: 'L' }, 50, 'new10')

We might be able to guess some of them, but it’s not very clear what is being passed here. Additionally, we need to mentally parse each value to map it to something meaningful.

The only thing I can guess here is { color: 'blue', size: 'L' }, which are the attributes of the product the user is purchasing. But what are these three numbers—456, 2, and 50—for? What's the last string, new10, for?

Now, if it were written like the following, we would understand it instantly:

addToCard({
  productId: 456,
  quantity: 2,
  attributes: { color: 'blue', size: 'L' },
  price: 50,
  discountCode: 'new10'
})

That's what we call Named Parameters.

How the function is defined

The above example is for the caller side. When defining the function, we use destructured parameters to explicitly indicate what parameters we expect—it also makes the function's parameter list more readable.

So instead of this:

const addToCard = (data) => {}

Write this:

const addToCard = ({ productId, quantity, attributes, price, discountCode }) => {}

Default values

With named parameters, you can still define default values for the parameters.

const addToCard = ({
  productId,
  quantity = 1,
  attributes,
  price,
  discountCode
}) => {}

In this example, we set quantity to 1, so you can pass the other parameters without quantity, and it will use 1 for it.

A common pitfall

If, for some reason, the function can be called without any parameters, like this addToCall(), you will get an error because it cannot destructure undefined.

addToCall()
// TypeError Cannot destructure property 'productId' of 'undefined' as it is undefined.

To fix it, set the default value of the whole object to {}.

const addToCard = ({ productId, quantity, attributes, price, discountCode } = {}) => {}

One parameter

You'll often hear that it's best to use named parameters when you have more than two or three parameters. I think you should use them even for one parameter, because knowing what you're passing is the goal.

For example, can you tell what this argument is for?

processPayment(true)

Now with named parameters:

processPayment({ notifyUser: true })

All the good things

Named parameters can drastically improve your code.

They make your code easier to read—you know what arguments are being passed.

You don't need to remember the order of the parameters. You can pass addToCard({ quantity: 5, productId: 456 }) or addToCard({ productId: 456, quantity: 5 })—either works!

More flexible default values—you don't have to define parameters with default values as the last ones.

More scalable—you can add more parameters without breaking current calls. Just add the new parameter anywhere; the order doesn't matter.

🔗 Let's stay connected:

🌐 Blog: https://tahazsh.com/
🎥 YouTube: https://www.youtube.com/@tahazsh
𝕏 Twitter/X: https://twitter.com/tahazsh
🦋 Bluesky: https://bsky.app/profile/tahazsh.bsky.social
🐘 Mastodon: https://fosstodon.org/@tahazsh

Strategy pattern is better when done with functions

Taha Shashtari — Sun, 22 Dec 2024 17:19:10 +0000

The typical example is you accept multiple payment methods—credit card, PayPal and crypto. And based on the user's choice, you will handle the payment differently. If, for example, they chose PayPal, you need to work with the PayPal API to process the payment.

If you're coming from an OOP language, the best way to implement it is using the Strategy pattern.

The OOP way

Here's how the OOP version would look like:

interface IPayment {
  processPayment(amount: number): void
}

class PaymentProcessor implements IPayment {
  private paymentStrategy: IPayment

  constructor(strategy: IPayment) {
    this.paymentStrategy = strategy
  }

  processPayment(amount: number): void {
    this.paymentStrategy.processPayment(amount)
  }

  setPaymentStrategy(strategy: IPayment) {
    this.paymentStrategy = strategy
  }
}

class CreditCardPayment implements IPayment {
  processPayment(amount: number): void {
    console.log(`$${amount} was processed with Credit card`)
  }
}

class PayPalPayment implements IPayment {
  processPayment(amount: number): void {
    console.log(`$${amount} was processed with PayPal`)
  }
}

class CryptoPayment implements IPayment {
  processPayment(amount: number): void {
    console.log(`$${amount} was processed with Crypto`)
  }
}

// Usage
const paymentProcessor = new PaymentProcessor(new PayPalPayment())
paymentProcessor.processPayment(100)
// Output: $100 was processed with PayPal

Lots of typing for a single method. Very verbose!

If you're working with a strictly OOP language, like Java, that might be your only option. But if your language supports functions as first-class citizens, like JavaScript, going with the functional approach is much cleaner.

The functional way

Here's how it would look with functions:

type PaymentStrategy = (amount: number) => void

function processPayment(strategy: PaymentStrategy, amount: number) {
  strategy(amount)
}

const creditCardPayment: PaymentStrategy = (amount: number) => {
  console.log(`$${amount} was processed with Credit card`)
}

const paypalPayment: PaymentStrategy = (amount: number) => {
  console.log(`$${amount} was processed with PayPal`)
}

const cryptoPayment: PaymentStrategy = (amount: number) => {
  console.log(`$${amount} was processed with Crypto`)
}

processPayment(paypalPayment, 100)
// Output: $100 was processed with PayPal

No boilerplate and much cleaner!

Because functions are much smaller units than classes, reusing, replacing, and mocking them is much simpler. You don't need to instantiate a class and set dependencies; you just deal with one function.

With functions, you pass what you just need

In OOP, we use ISP (Interface segregation principle) to ensure that classes don't depend on methods they don't use.

Using the same example, here's how verbose your code will be without using ISP.

interface IPayment {
  processPayment(amount: number): void
}

interface PaymentStrategy {
  processPayment(amount: number): void
  email(): string
  creditCardNumber(): string
  publicKey(): string
  privateKey(): string
}

class PaymentProcessor implements IPayment {
  // same
}

class CreditCardPayment implements PaymentStrategy {
  private _creditCardNumber: string

  constructor(creditCardNumber: string) {
    this._creditCardNumber = creditCardNumber
  }

  processPayment(amount: number): void {
    console.log(
      `$${amount} was processed with Credit card using credit card number ${this.creditCardNumber()}`
    )
  }

  creditCardNumber(): string {
    return this._creditCardNumber
  }

  email(): string {
    throw new Error('Method not implemented.')
  }
  publicKey(): string {
    throw new Error('Method not implemented.')
  }
  privateKey(): string {
    throw new Error('Method not implemented.')
  }
}

class PayPalPayment implements PaymentStrategy {
  private _email: string

  constructor(email: string) {
    this._email = email
  }

  processPayment(amount: number): void {
    console.log(
      `$${amount} was processed with PayPal using email ${this.email()}`
    )
  }

  email(): string {
    return this._email
  }

  creditCardNumber(): string {
    throw new Error('Method not implemented.')
  }
  publicKey(): string {
    throw new Error('Method not implemented.')
  }
  privateKey(): string {
    throw new Error('Method not implemented.')
  }
}

class CryptoPayment implements PaymentStrategy {
  // ...
}

// Usage
const paymentProcessor = new PaymentProcessor(new CreditCardPayment('1234'))
paymentProcessor.processPayment(100)

const paymentProcessor2 = new PaymentProcessor(
  new PayPalPayment('test@example.com')
)
paymentProcessor2.processPayment(100)

const paymentProcessor3 = new PaymentProcessor(
  new CryptoPayment('public_key', 'private_key')
)
paymentProcessor3.processPayment(100)

In this code, we have a single interface for all payment strategies. But not all of the methods are used. For example, for PayPal we just need the email, no need for the rest.

To fix it, we can follow ISP and separate the interface into multiple smaller interfaces, each one for a specific payment method.

But why do that when we can avoid all of this with the functional approach.

type PaymentStrategy = (amount: number) => void

function processPayment(strategy: PaymentStrategy, amount: number) {
  strategy(amount)
}

const creditCardPayment = (creditCardNumber: string): PaymentStrategy => {
  return (amount: number) => {
    console.log(
      `$${amount} was processed with Credit card using credit card number ${creditCardNumber}`
    )
  }
}

const paypalPayment = (email: string): PaymentStrategy => {
  return (amount: number) => {
    console.log(`$${amount} was processed with PayPal using email ${email}`)
  }
}

const cryptoPayment = (publicKey: string, privateKey: string): PaymentStrategy => {
  return (amount: number) => {
    console.log(
      `$${amount} was processed with Crypto using public key ${publicKey} and private key ${privateKey}`
    )
  }
}

// Usage
processPayment(creditCardPayment('1234'), 100)
processPayment(paypalPayment('test@example.com'), 100)
processPayment(cryptoPayment('publicKey', 'privateKey'), 100)

With the power of closures and partial application, we converted each payment function into a single-input function after specifying the needed details (like email for PayPal).

For instance, calling paypalPayment('test@example') returns another function that accepts the amount: (amount: number) => void. Now passing that second function to processPayment function will work, because that's what it's expecting.

That's why functions are better for the Strategy pattern

It’s less boilerplate, easier to test and mock, and avoids bloated interfaces by providing only what’s needed (as we saw in the last example).

🔗 Let's stay connected:

𝕏 Twitter/X: https://twitter.com/tahazsh
🦋 Bluesky: https://bsky.app/profile/tahazsh.bsky.social
🐘 Mastodon: https://fosstodon.org/@tahazsh
🎥 YouTube: https://www.youtube.com/@tahazsh
🌐 Blog: https://tahazsh.com/

Why you shouldn't use async and defer in the same script tag

Taha Shashtari — Sun, 15 Sep 2024 13:32:07 +0000

To answer that question, let's first understand how <script> tags are downloaded and executed.

When the browser receives the HTML response, it starts parsing it incrementally from top to bottom. While parsing, if it encounters a <script> tag (without async or defer), it stops parsing the HTML until the JavaScript is downloaded and executed.

However, when using async or defer, the JavaScript will be downloaded (but not executed) in parallel with HTML parsing.

The key difference between async and defer is when the scripts are executed.

Async scripts will execute as soon as they are downloaded, which can pause the HTML parser.

Defer scripts will execute only after the entire page has been fully parsed and rendered.

Since async scripts execute before the page is fully ready, you might get errors when trying to access DOM elements from them.

On the other hand, defer scripts wait until the page is fully rendered, so you can safely access DOM elements from them.

What are async scripts useful for?

They are great for tasks that don’t involve DOM manipulation. Examples are like analytics tools, fetching third-party ads, and social media widgets.

Because async scripts execute while the page is still being parsed, they are great for preparing and fetching data, like for ads, before the page finishes rendering. This can make the initial load faster.

What happens if you use both async and defer on the same script?

Most modern browsers prioritize async over defer, which can lead to errors if you try to access the DOM from that script.

That’s why you should use either defer or async, but not both, for your scripts!

🔗 Let's stay connected:

𝕏 Twitter/X: https://twitter.com/tahazsh
🎥 YouTube: https://www.youtube.com/@tahazsh
🌐 Blog: https://tahazsh.com/

Why the number of Gleam programmers is growing so fast?

Taha Shashtari — Tue, 26 Mar 2024 13:48:38 +0000

Because it's so good! Hear me out, Gleam has beautiful syntax; it's small yet very powerful.

Recently, Gleam has gained more popularity, and a lot of developers (including me) are learning it. At the time of this writing, it has exceeded 14k stars on GitHub; it grew really fast for the last month.

I'm sure there are other good reasons why Gleam is so good, but here are the reasons and features that I love Gleam for.

It's small and simple

One of the reasons many developers prefer C over other languages like C++ is that it's small.

And it's the same for Gleam; it's so small that you can learn it in an afternoon.

Small languages are good because they are fast to learn, fast to compile, and have fewer ways of doing things, which makes the code easier to read and reason about.

If you are interested in learning more about the good philosophy behind simple languages, check out this amazing article by Ryan Brewer.

Nice syntax

Gleam syntax is concise and easy to read. It saves you keystrokes when the full words are not necessary, for example fn instead of function, and pub instead of public.

One example I really liked is function captures. It's helpful when you want to use partial application with closures. It makes the code much shorter and easier to read.

Here's how I would implement the same example in both JavaScript and Gleam:

In JavaScript:

function add(a, b) {
  return a + b
}

const addOne = (function () {
  return function (b) {
    return add(1, b)
  }
})()

console.log(addOne(10)) // 11

In Gleam:

fn add(a: Int, b: Int) -> Int {
  a + b
}

pub fn main() {
  let add_one = add(1, _)
  io.debug(add_one(10)) // 11
}

It's explicit

Since Gleam is a typed language, you will work with different types like floats and integers. Instead of guessing what both operand types are, you can know immediately from the operator type.

// Integers use the regular operator symbols
let add = a + b
let multiply = a * b
let compare = a > b
// and the others...

// Floats adds a dot after the operator
let add = a +. b
let multiply = a *. b
let compare = a >. b
// and the others...

I don't know about you, but this explicitness makes the code easier to understand and reason about for me.

Labelled arguments

The number of programming languages that support labelled arguments is relatively small. So, while it's not unique to Gleam, it's still one of the best decisions.

With labelled arguments, you don't have to remember the order of arguments when calling a function or go to the function definition to know what they are about.

Look at this example:

import gleam/io

fn log_message(message msg: String,  level message_type: String) {
  io.println("[" <> message_type <> "] " <> msg)
}

pub fn main() {
  // When calling it you can change the order of arguments
  log_message(level: "Error",  message: "Record not found")
}

The cool thing about labelled arguments in Gleam is that you can give the argument a different label than the parameter name; see how msg is labelled with message and message_type with level. This is good when you want to provide a clearer name for the public API that is different from the internals.

Pipelines

Since Gleam is a functional language, you will write a lot of composed functions, meaning that the output of one function becomes the input to the next function.

With pipelines, your code will be much clearer and easier to read.

Here's an example without pipelines:

wrap_with_parenthesis(to_uppercase(remove_duplicate(letters)))

And here's with pipelines:

letters
  |> remove_duplicate
  |> to_uppercase
  |> wrap_with_parenthesis

Reading code that uses pipelines is much more intuitive because we are reading step by step, from the value to the last function; whereas, without pipelines, you need to read from the value passed to the most inner function to the most outer one, which is more difficult to read.

Powerful flow control

While Gleam doesn't have an if statement or return keyword (yes, you heard it correct), it provides a much more powerful way called pattern matching.

If you are coming from a language that supports pattern matching, like Rust, you will instantly know what that means. Otherwise, it will feel odd to you at first. But once you learn it, you'll see why it's a better approach than other the ones.

Let me show you a quick example that I got from an exercise on exercism.

Let's say you have a string "[ERROR]: The error message", and you want to extract the message that comes after [ERROR]:. With pattern matching you can simply do this:

pub fn get_message(log_line: String) -> String {
  case log_line {
    "[ERROR]:" <> msg -> msg
    _ -> log_line
  }
}

If you are not familiar with the syntax, it will feel confusing at first. But basically it just matches the message that comes after [ERROR] on this line: "[ERROR]:" <> msg -> msg. It gets rid of [ERROR]: and just returns the message.

I didn't need any library or regular expression to do that. I'm just using the basic syntax of Gleam.

Developer friendly

There are tools that Gleam provides to improve the developer experience. My two top examples are the todo and @deprecated keywords.

With todo, you can mark a specific function as unimplemented and provide a message for the reason.

pub fn do_something() {
  todo as "I need to get other_function ready first"
}

And with @deprecated, you can mark some function as deprecated and provide directions to what the user should use instead.

@deprecated("Use new_function instead")
fn old_function() {
  Nil
}

Friendly community

No matter how many questions you have, or how difficult or easy they are, you can ask them on the Gleam Discord's channel and you will get the answer.

Seeing how friendly and helpful the community is makes me enjoy working with Gleam more.

Start learning Gleam

If you are interested in learning Gleam, start with their language tour, and then I highly recommend doing the exercises on Exercism. They are exceptionally good!

🔗 Let's stay connected:

🌐 Blog: https://tahazsh.com/
𝕏 Twitter/X: https://twitter.com/tahazsh
🐘 Mastodon: https://fosstodon.org/@tahazsh
🎥 YouTube: https://www.youtube.com/@tahazsh

Mastering closures in JavaScript

Taha Shashtari — Wed, 20 Mar 2024 10:42:22 +0000

Closures are one of the most confusing concepts for new JavaScript learners. They are very powerful. Once you understand them well, your JavaScript skills will move to the next level.

In this article, I will give you all the knowledge you need to understand closures well. We will start with defining what scoping is and the different types of scoping. Then, we will learn the different ways to define variables in JavaScript. And we will move in small steps until we see how closures are defined. At the end of this article, I will show 5 different practical applications of closures that you can use now in your JavaScript code.

What is scoping?

In simple terms, scoping is the rules that determine how a variable (or function or class) is evaluated and accessed.

For example, we say that this variable's scope is some function or some if statement, and sometimes we say that its scope is global, meaning we can access it and modify it from anywhere.

Here are a couple of scoping examples.

// a is global variable
var a = 5

function fun() {
  // b's scope is only within the function fun
  let b = 'foo'

  if (b === 'foo') {
    // c's scope is only within this if statement
    let c = 'bar'
  }
}

Static (lexical) vs. dynamic scoping

We always hear that JavaScript is a lexical scoping language, but it's not really clear what that means.

To understand what that means, we need to understand the alternative: dynamic scoping.

In some old languages, like Lisp and Bash, dynamic scoping was used. However, most modern languages stopped using it because dynamic scoping can lead to unpredictable behavior.

It can lead to that because variable scopes are determined based on the calling context at runtime. Let me make this clear with an example.

Take a look at this code:

let v = 10

// Called by b()
function a() {
  return v
}

// b() has its own variable named as v and calls a()
function b() {
  let v = 20
  return a()
}

console.log(b())

If I asked you what value console.log(b()) will log, it will be an obvious answer: 10.

It's 10 because function a() returns v, and v is defined above and has the value 10.

That's how static (also called lexical) scoping works. You can know the value just by looking at the code.

If dynamic scoping were what JavaScript uses, the logged value would be 20. It would be 20 because when running the code, function b() would override the scope used for the variable v to the one defined in b(), and that would make a() use the last one, which is 20.

Thankfully, JavaScript doesn't use dynamic scoping and uses lexical scoping instead.

So you can simply think of lexical scoping as the scoping that allows us to know what variable will be used just by looking at the code at compile time (if the language is compiled) and not at runtime.

`let` and `const` vs. `var`

Advice everyone gets when learning JavaScript is to always use let and const instead of var. But why is that? Is var bad? Not necessarily.

It's all about scoping.

let and const are block scoped, while var is function scoped. What does that mean?

It means that any variable declared with let or const will be available only within the block it was defined in. By block, I mean {} (curly braces).

This literally means this:

let a = 'foo'

{
  let b = 'bar'
  console.log(b) // Output: 'bar'
}

console.log(b) // Error: undefined

Look how I defined a block even without any additional keyword like if or for. And that's a valid syntax, but in real-world code, the blocks are usually preceded with some keywords like when defining if statements, while loops, and functions.

This is why when we use let and const in if statements, for example, we can't use the variable outside of it.

if (true) {
  // Here is a new scope (inner scope)
  const a = 'foo'
}

// Here is the outer scope (another one)
console.log(a) // Error: undefined

So console.log logged undefined because it's in a different scope from the if statement. This means you can define the variable a again in the outer scope without affecting the one in the inner scope.

if (true) {
  const a = 'foo'
}

const a = 'bar'
console.log(a) // bar

So that's how let and const scoping works. Let's see how var works.

var is for defining function-scoped variables. This means it will create a new scope only if it was used within a function, like this:

function foo() {
  var a = 'foo'
}

console.log(a) // Error: undefined

Note that var is only function scoped (not block scoped), which means defining it within an if statement, for example, will define it globally (on the window object if in the browser).

if(true) {
  var a = 'foo'
}

console.log(a) // foo

So var will define a new scope if it's used in a function; otherwise, it will define the variable in the global scope.

Thus, we get the advice to prefer let and const over var because block-scoped variables are more predictable and easier to reason about.

Access direction

An important rule to remember in lexical scoping: inner scopes can access outer scopes, but not the other way around.

Here's an example:

let a = 1

// cannot access b or c

{
  // can access a
  // cannot access c

  let b = 2

  {
    // can access a
    // can access b

    let c = 3
  }
}

You can think of it as: you can't look inside things, but you can look outside them.

You need to always remember this rule as closures heavily depend on it as you will see next.

It also works for functions

Until now, we've been looking at examples that show how scoping works for variables. But the same is true for functions.

Let's take a look at this example:

function a() {
  function b() {
    console.log('from b')
  }

  b()

  console.log('from a')
}

b() // Error: b is not defined

It errors because function b is not defined within the scope of the caller.

If we modify the example to call a() instead, it will work because a is defined within the scope of the caller.

function a() {
  function b() {
    console.log('from b')
  }

  b()

  console.log('from a')
}

a()
// Output:
// from b
// from a

Also note how it was able to call function b from function a because b is defined within the scope of a.

In this example, we have nested functions, so we are really close to the concept of closures (get ready).

Returning a function from another function

Let's take the previous example and modify it to return the function b from the function a.

function a() {
  return function b() {
    console.log('from b')
  }
}

const nestedFunction = a()

nestedFunction() // Output: from b

Notice how we were able to overcome the restriction of scopes by returning the function. In the previous example, we weren't able to call function b directly in the outer scope, but when we returned the function b, we were able to access it and call it.

Let's stop for a moment here to talk about the idea of returning a function.

When in a language a function can return another function (or take functions as arguments), we say two things:

this language supports functions as first-class citizens
and we call that function a Higher-order function (HoF).

Actually, this is why we say JavaScript supports functional programming.

One more step to create a closure

Let's take the previous example and make function b use (return) a variable defined in function a.

function a() {
  let v = 10
  return function b() {
    return v
  }
}

const nestedFunction = a()

console.log(nestedFunction()) // Output: 10

Believe it or not, you have created your first closure.

Here's the simplest definition of a closure:

A closure is a function that uses and retains access to a variable defined outside of its scope.

Two important things to note here: uses and retains access.

The word uses here means that the function can use the outside variables without the need to pass them as parameters.

And retains access means that the inner function will still have access to the outside variables even after the outer function finishes executing.

So in the example above, even after the function a() finished executing, the variable v was not removed by the garbage collector because the inner function b() might need to use it in the future.

A small note here: a function doesn't have to use outside variables to be considered a closure; it's still called a closure even if it's empty, but that's not a common thing we see.

Closures can also modify outer variables

Not only can closures access outer variables, but they can also modify them if they were defined with let.

function a() {
  let counter = 0
  return function b() {
    return counter++
  }
}

const nestedFunction = a()

console.log(nestedFunction()) // Output: 0
console.log(nestedFunction()) // Output: 1
console.log(nestedFunction()) // Output: 2

You can return multiple closures from a function

This is not a feature specific to closures, but it's a feature of JavaScript that is worth mentioning.

Let's modify the previous example to return two functions instead of one by returning an object.

function makeCounter() {
  let counter = 0
  return {
    inc() {
      return ++counter
    },

    getValue() {
      return counter
    }
  }
}

const counter = makeCounter()

console.log(counter.inc()) // Output: 1
console.log(counter.inc()) // Output: 2
console.log(counter.inc()) // Output: 3

console.log(counter.getValue()) // Output: 3

It's still the same idea, but this is how we usually return multiple closures.

Why closures?

Like anything in programming, there are many different ways to implement something. And closures are no different. While anything can be implemented without closures (for example, in languages that don't support closures), closures provide a much simpler and more intuitive way to do so.

The first case that comes to mind for closures in JavaScript is event handling. Let's take a look at this example:

let counter = 0

button.addEventListener('click', () => {
  counter++
  console.log(counter) // 1 .. 2 .. 3 ..
})

While this is a simple example, there are a few things to unpack:

We have two scopes here: outer scope (where counter is defined), and inner scope for the callback defined in addEventListener.
Since the inner function has access to the outer scope, we consider it a closure.
This function gets called every time the user clicks the button.
Every time it's called, it increments the outer variable counter and logs it.

Look how easy event handling is because of closures. Because the closure maintains access to its outer scope, we were able to modify and log counter on each click.

This example shows us how closures are everywhere, and we might be using them without realizing.

There are other cases where you want to create closures intentionally. And here are five different real-world examples of closures.

Example 1: Encapsulation

Like in Object-oriented programming (OOP), we can achieve encapsulation through closures. Encapsulation essentially means hiding part of the data and the internal implementation.

In OOP, we can do this using the private keyword. In closures, we can simply do that by defining the data outside the closure, like this:

function makeCounter() {
  // Private data
  let counter = 0

  // Private function
  function a() {}

  // Public
  return {
    inc() {
      counter++
    },

    dec() {
      counter--
    },

    getCounter() {
      return counter
    }
  }
}

const counter = makeCounter()

counter.inc()

console.log(counter.getCounter())

In this example, there's no way you can access counter or the function a() directly. You can only do that through its public API; in other words, the object returned from it.

Example 2: Partial application

In mathematics, partial application means fixing a certain number of arguments in a function to create a new function with fewer arguments.

If that's a little bit confusing, don't worry. Here's a simpler explanation.

Let's say you have a function f(a, b, c). This function takes three arguments: a, b, and c. Partial application means creating another function from function f where some arguments are hardcoded. For example, we can have a new function called g(b, c), where a is always the value 10, for example.

We can do the same in JavaScript because functions are first-class citizens.

Let's take a look at this example:

function add(a, b) {
  return a + b
}

function add10(b) {
    return add(10, b)
}

console.log(add10(5)) // Output: 15

In this example, we created another function called add10 based on the original one add. The new function does the same but always uses the number 10 as the first argument.

This example is just for demonstration purposes, so it might not look useful. Let's take a look at a useful example that you might use in your project.

function createFormatter(prefix, suffix) {
  return function (string) {
    return `${prefix}${string}${suffix}`
  }
}

const bracketsFormatter = createFormatter('[', ']')
const paragraphFormatter = createFormatter('<p>', '</p>')

console.log(bracketsFormatter('name')) // [name]
console.log(paragraphFormatter('some text')) // <p>some text</p>

You can see how we were able to create different types of formatters using the general one createFormatter. If I want to create another formatter that surrounds text with curly braces, I just need to do this:

const curlyFormatter = createFormatter('{', '}')

So, with partial applications, we can make a certain function more reusable and flexible by fixing some of its arguments. All thanks to closures for enabling us to do that.

Example 3: Validation functions

In this example, I want to create a way to validate values. If they are valid, don't do anything; otherwise, throw an error. With closures, we can do that easily.

function createValidator(validatorFunction, errorMessage) {
  return function (value) {
    if (!validatorFunction(value)) {
      throw new Error(errorMessage)
    }
  }
}

const positiveValidator = createValidator((value) => {
  return value > 0
}, 'The provided number must be positive')

try {
  positiveValidator(-10) // will throw an error
} catch (error) {
  console.log('error', error)
}

positiveValidator is just one example. You can use createValidator to create any validator you want.

Example 4: Throttling

Another good application of closures is throttling, where a function is called only once per some duration.

function throttle(callback, duration) {
  let lastExecuted = 0

  return function (...args) {
    const now = Date.now()
    if (now - lastExecuted >= duration) {
      callback(...args)
      lastExecuted = now
    }
  }
}

const saveRequest = throttle((data) => {
  console.log('saving data', data)
}, 1000)

// Only one request is sent
saveRequest({ user: 'test' })
saveRequest({ user: 'test' })

As an exercise, see how you can modify the throttle function to be a debounce function.

Example 5: Memoization

Memoization simply means caching the result of some expensive function.

In the following example, I'm writing a memoization function for addition, but in the real world, it will be something more expensive.

function memoizedAdd() {
  const cache = {}

  function addFunc(a, b) {
    console.log('adding')
    return a + b
  }

  return function (a, b) {
    const key = `${a},${b}`
    if (cache[key]) {
      return cache[key]
    }
    const result = addFunc(a, b)
    cache[key] = result
    return result
  }
}

const add = memoizedAdd()

console.log(add(10, 5))
console.log(add(10, 5))
console.log(add(10, 1))

// Output:
// adding
// 15
// 15
// adding
// 11

You can see how the word adding was logged only once for adding 10 and 5, since the second time used the cached result. Imagine how beneficial this would be for expensive operations.

Conclusion

Closures are a fundamental part of JavaScript, and we are already using them every day without realizing—just like in the event handling example.

Understanding them well helps us write code that's more reusable and flexible. In this article, I've shown you five different examples of how closures can be used, but there's no limit to what you can come up with.

Whenever you forget what closures are, just remember that they're basically functions that remember their surroundings.

There are countless applications of closures. Are there any that haven't been mentioned in this article? Please share them in the comments section.

🔗 Let's stay connected:

🌐 Blog: https://tahazsh.com/
🎥 YouTube: https://www.youtube.com/@tahazsh
𝕏 Twitter/X: https://twitter.com/tahazsh

Software design patterns and principles are not the goal

Taha Shashtari — Tue, 12 Dec 2023 17:13:03 +0000

The worst thing programmers have to deal with is fixing a bug or adding a feature in code that is hard to understand and change.

The only solution to this is to write code that is easy to change.

Easier said than done.

Countless books and articles teach about design patterns and design principles (like SOLID or DRY) to help achieve that. The issue with them is that they work as shortcuts, and the problem with shortcuts is that they are not enough to properly learn the skill. You also have to practice.

Writing easy-to-change code is not easy!

It's not easy because it's a skill. Skills require practice and time to improve, and, more importantly, knowing how to improve them.

For most skills, there are clear steps to take for improvement. For example, if you want to learn how to play the piano, you need to familiarize yourself with the keyboard, practice hand posture and finger positions, learn about note names and positions, all the way until you train your muscle memory to play the song you want without thinking.

Unfortunately, for programmers, it's not that straightforward. There are plenty of books that talk about best practices and principles, but none of them guarantee writing good code that is easy to understand and change six months later.

You can learn all the design patterns, principles, and refactoring techniques out there, but when it comes to writing real code in a real job, you don't know how to apply them.

So, are they useless, and should you not learn them? Of course not! Most of them are good and were created by smart people for real-world scenarios.

But the problem is that you don't have enough experience and failures to know which ones to use.

Having enough experience doesn't mean having worked for 10 years as a programmer. There are programmers who have been in the industry for a very long time, and they are still writing code that is hard to change.

The key here is to be conscious and deliberate about practicing writing good code. You do this by taking a few minutes before writing code to think about the best way to write it. You have to predict how this function (or object, or whatever) will be used by other parts of the software and how changing it would affect the other parts.

Sometimes, a certain design pattern will come to your mind, and you would try it. And most of the time, you will realize that it wasn't appropriate and it's making the code more complex than necessary.

Other times, you would think that this code should be simple and just include it in a single function along with other code. But the more you add, the more difficult your code will be to read and change. Then, you might start to think about breaking this function into multiple ones or even introduce new objects.

But you will never know what is better until you try that. And it will be painful to see how spending too much time on something to make it cleaner turns out to be even worse. And that's okay. Actually, that's the only true way to learn how to write good code.

The more you fail at writing good code, the more you will be able to predict what will work and what won't in the future. Other developers would be impressed when you know right away what pattern to use or how splitting function makes things much easier. And they will think you are a code wizard. But you are not! It's only because you practiced this a lot that you instantly know if something will be good or not.

We always hear developers say, 'Make things simpler. Don't use patterns or principles, or your code will end up worse.' But that's not true. It all depends on the context of your code and how it will be used.

Writing simple code doesn't mean avoiding patterns or OOP principles. Instead, it means using the best techniques and tools to make the code easier to read and change. It might require a design pattern or not.

Let me give you a real example.

An example that doesn't need a design pattern

If I want to write a function that returns the discount percentage based on the user type, I wouldn't use the abstract factory pattern to add an object for each case. So, I wouldn't write it like the following 'to replace conditionals with polymorphism'.

function getDiscountForUser(user) {
  return createUserDiscount(user).getDiscount()
}

function createUserDiscount(user) {
  switch (user.type) {
    case 'premium':
      return new PremiumUserDiscount()
    case 'gold':
      return new GoldUserDiscount()
    case 'banned':
      return new BannedUserDiscount()
    default:
      return new UserDiscount()
  }
}

class PremiumUserDiscount {
  getDiscount() {
    return 0.4
  }
}

class GoldUserDiscount {
  getDiscount() {
    return 0.6
  }
}

class BannedUserDiscount {
  getDiscount() {
    return 0
  }
}

class UserDiscount {
  getDiscount() {
    return 0.2
  }
}

I will instead write it like this:

function getDiscountForUser(user) {
  switch (user.type) {
    case 'premium':
      return 0.4
    case 'gold':
      return 0.6
    case 'banned':
      return 0
    default:
      return 0.2
  }
}

For this case, this is good enough. If, in the future, I need to add more logic to it, then I will consider the best refactoring needed to keep it simple while remaining easy to change.

An example that needs a design pattern

In the next example, using the abstract factory pattern would significantly simplify the code.

To provide some context, I was working on Veloxi, a JavaScript library for creating smooth interactions. A major aspect of it involved implementing animations for specific properties, like position, rotation, or size.

Some properties, such as position and size, are represented with two values: x and y. This means we can represent them with a Vector2D object. However, for other properties, like rotation, only one number is needed to represent them (e.g. rotation degrees).

In Veloxi, I needed to support various types of animations, including tween animations and spring animations.

Each animation type requires its own implementation. In fact, for each animation type, I needed to implement two different versions: one for numbers and one for Vector2D objects.

The relationships between different parts of this code are more complex than in most cases. I have different properties, each with a different value representation (2D vector or number). For each value type, I need to implement all the animation types available.

In this scenario, it's clear that I need a well-structured way to represent these relationships and the way to create them. After thinking, I decided that using the abstract factory pattern would be the best choice.

// ************************************************************
// ** Both PositionProp and RotationProp don't know
// ** what type of animator they are using.
// ** It can be for Vector2D or Number.
// ** And it can be tween or spring.
// ************************************************************

class PositionProp {
  // currentValue is a Vector2D object
  currentValue

  // targetValue is a Vector2D object
  targetValue

  constructor(animatorFactory) {
    this.animatorFactory = animatorFactory
    this.animator = animatorFactory.createAnimatorByName('tween')
  }

  setAnimator(animatorName) {
    this.animator = this.animatorFactory.createAnimatorByName(animatorName)
  }

  // Update loop
  update() {
    this.currentValue = this.animator.update(
      this.currentValue,
      this.targetValue
    )
  }
}

class RotationProp {
  // currentValue is a number value
  currentValue

  // targetValue is a number value
  targetValue

  constructor(animatorFactory) {
    this.animatorFactory = animatorFactory
    this.animator = animatorFactory.createAnimatorByName('tween')
  }

  setAnimator(animatorName) {
    this.animator = this.animatorFactory.createAnimatorByName(animatorName)
  }

  // Update loop
  update() {
    this.currentValue = this.animator.update(
      this.currentValue,
      this.targetValue
    )
  }
}

// ************************************************************
// ** Tween Animators for both Vector2D and numbers
// ************************************************************

class Vec2TweenAnimator {
  update(currentValue, targetValue) {
    // ...
  }
}

class NumberTweenAnimator {
  update(currentValue, targetValue) {
    // ...
  }
}

// ************************************************************
// ** Spring Animators for both Vector2D and numbers
// ************************************************************

class Vec2SpringAnimator {
  update(currentValue, targetValue) {
    // ...
  }
}

class NumberSpringAnimator {
  update(currentValue, targetValue) {
    // ...
  }
}

// ************************************************************
// ** Animator factories for both Vector2D and number
// ************************************************************

class Vec2AnimatorFactory {
  createAnimatorByName(animatorName) {
    switch (animatorName) {
      case 'tween':
        return new Vec2TweenAnimator()
      case 'spring':
        return new Vec2SpringAnimator()
      default:
        return new Vec2TweenAnimator()
    }
  }
}

class NumberAnimatorFactory {
  createAnimatorByName(animatorName) {
    switch (animatorName) {
      case 'tween':
        return new NumberTweenAnimator()
      case 'spring':
        return new NumberSpringAnimator()
      default:
        return new NumberTweenAnimator()
    }
  }
}

// ************************************************************
// ** Here's the code for creating the property objects
// ************************************************************

const positionProp = new PositionProp(new Vec2AnimatorFactory())
const rotationProp = new RotationProp(new NumberAnimatorFactory())

I think this code is well-structured for this use case. If, for example, I need to update how the spring animation is implemented for 2D vectors, I know exactly what to modify, and the same is true for adding a new animation type.

How to know what pattern to use?

In the example above, I didn't know I needed to use this pattern just because I read about it in the past. I recognized the need because of numerous past failures in implementing similar code—code where there is a complex relationship between its parts, and I needed a clear way to set up those components.

So, in this example, the focus is on the creation of those parts (objects) and the relationships between them. After exploring popular creational patterns, I found that the abstract factory fits well here.

It's important to note that I'm not claiming that using this pattern here is the absolute best way to implement this code. Others might come up with better solutions. However, there's no doubt that using the abstract factory pattern here fits well.

When to look for patterns to use in your code?

Every time I encounter difficulty modifying the code, it's a hint for me that it can be written better. Does it have to be rewritten using a certain design pattern or following some principle? Of course not! The goal is not to know every pattern out there; the goal is to make the code easy to change, even if I have to invent my own patterns.

I typically view design patterns as inspiration for solving design problems in code. They are great for helping me recognize design problems faster.

The best way to implement a pattern

The implementation is not the important thing here. In most cases, following their exact way of implementation doesn't help due to differences in programming languages, use cases, and the domain of the project. Only with practice will you know the best way to implement the pattern—or maybe create your own pattern.

It's not about using design patterns or principles

A constant reminder I keep telling myself is that the goal is not about using design patterns or principles. The ultimate goal is to write code that is easy to change.

Sometimes breaking the DRY principle and duplicating the code is the best choice for your current implementation. I can think of two examples. The first one is when the code will start the same in two places, but you know that one of them will change drastically in the future. Another example is when making the code reusable requires workarounds that will make your code end up worse.

Many people feel bad that they don't understand all the patterns and principles out there, but they shouldn't.

Design patterns are the result of other people's experiences. Others found that a certain design problem occurs frequently, and they gave it a label to make it easier to recognize them in the future.

It's very likely that their solutions won't fit well in your problems. However, knowing about them will make it easier for you to recognize similar problems and come up with similar solutions.

Design principles, on the other hand, work as checks. They are a great way to ask ourselves some questions before we write code. For example: "Do I need to make this function reusable?" or "Should I split this into multiple modules to improve responsibility?" They are just checks; you don't have to follow them. Do what's best for your current implementation.

The goal here is to build intuition for writing scalable and easy-to-change code; following a design pattern or not is not the point.

A practical advice

Read about patterns. Read about principles. Read others' open-source code for inspiration.

Before you start writing code, take a few minutes to consider the best way to write it. Don't use a pattern just because it exists. Instead, think about the simplest solution you can come up with at the moment. Use it.

When you revisit that code for modifications, assess how difficult it is to modify. Based on that, you'll know if your solution was good. If not, that's okay; you've learned a new way not to write code. Try another solution and evaluate.

The more you practice, the more it will become ingrained in your muscle memory, like learning the piano. And soon, you'll appear as a code wizard! Let's be code wizards!

🔗 Let's stay connected!

🌐 Blog: https://tahazsh.com/
🎥 YouTube: https://www.youtube.com/@tahazsh
𝕏 Twitter/X: https://twitter.com/tahazsh

[Video] Understand How to Submit Forms

Taha Shashtari — Mon, 27 Nov 2023 07:19:14 +0000

There are several things you need to think about before submitting data from your forms, such as what encoding type to use, whether it contains a file, and if you need to use JavaScript. In this video, I'll answer all these questions while walking you through several examples, showing the workflow from the client to the server.

Thanks for watching!

🔗 Let's stay connected!

🌐 Blog: https://tahazsh.com/
🎥 YouTube: https://www.youtube.com/@tahazsh
𝕏 Twitter/X: https://twitter.com/tahazsh

[Video] Introduction to Backend for Frontend Developers

Taha Shashtari — Wed, 15 Nov 2023 08:27:44 +0000

If you are a frontend developer and find backend development to be a black box, this will be your very first step into the world of backend development.

Thanks for watching! 😄

🔗 Let's stay connected!

🌐 Blog: https://tahazsh.com/
🎥 YouTube: https://www.youtube.com/@tahazsh
𝕏 Twitter/X: https://twitter.com/tahazsh

[video] Flip Card in CSS (Like Apple)

Taha Shashtari — Wed, 25 Oct 2023 18:37:02 +0000

Using flip cards is a great way to reveal additional content in a fun and interactive way. In this video, I will show you how to implement flip card animation in CSS, similar to the one on Apple’s site.

Please let me know if you have any questions in the comments.

Thank you for watching! 😄

How to Add Web Push Notifications to Your Web App

Taha Shashtari — Wed, 03 May 2023 20:44:40 +0000

Sending push notifications is a great way to communicate with your site's users even when they are not currently using your site. We get push notifications all the time from various apps on our phones such as Twitter, Instagram, and the Mail app.

It's a great time to start using web push notifications as it's now supported in all major browsers—including iOS devices, which was recently supported in iOS 16.4.

In this article, I'm going to show you how to use web push notifications by building an example from scratch.

Before we dive in, it's worth mentioning that using push notifications inappropriately can be annoying to users and considered a spam. These notifications should be sent for important updates that are timely, relevant, and precise. A good example is notifying the user when they receive a message to their inbox. A bad example is spamming the user with irrelevant ads and discounts, etc.

What is a push notification?

Web push notifications are the combination of two different technologies: Push Messages and Notifications.

A notification is the notification card you see on your phone's home screen or on your desktop, at the top-right corner of your screen.

A push message, on the other hand, is the technology for sending a message from a server to a client. It's called push because it pushes the message without the client asking for it—which is the opposite of the traditional request/response workflow.

So when I say push notification, I mean the workflow of pushing a message from the server to the client and then display it on the client side using the notification card component.

A general overview of the web push notification workflow

There are 6 main steps for sending a push notification:

Request permission from the user to display notifications.
Subscribe the user to your push notification service. This step gets you an object called PushSubscription. This object is used to identify which client to send the notification to. Each client has a different PushSubscription object. I'm saying a client, not a user, because a client is the browser the user is using. A user can have multiple clients—their desktop browsers (each browser is a different client) and their mobile browsers.
Store that PushSubscription object somewhere on your backend—in the database for example. You need to associate that object with the user of your application—for example store it as a new field in the users table; this depends on your application. To support multiple browsers for the user, you need to store a list of PushSubscription objects instead of one.
Get the PushSubscription object(s) of the user you want to notify, and then send them the message.
Listen to the push event in the service worker of your site. Remember service workers run on the frontend side of the site.
When the push event is triggered, get the message included in the notification sent from the backend, and then display it as a notification using the Notification API.

The first three steps are only run once for each notification subscription. Once the user is subscribed, it will run the last three steps for each notification you send.

Display a test notification

To display a notification, you need to get permission from the user first. To do that, you need to run this from your JavaScript:

Notification.requestPermission().then((permissionResult) => {
  if (permissionResult === 'granted') {
    console.log('Can show notifications')
  } 
})

Calling this function returns a promise with the permission result. The returned result can be one of these strings: default, granted, or denied. The default value is used when the user doesn't click "Allow" or "Block", and instead clicks the close button of the permission prompt.

In some browsers, like Safari, requesting notifications permission requires you to run it from a user gesture, meaning that the user has to do something first to allow for notifications, like clicking a button.

So, to test the above code, put it in a button click handler, like this:

<body>
  <button class="show-notification-button">
    Show Notification
  </button>

  <script>
    const button = document.querySelector('.show-notification-button')

    button.addEventListener('click', () => {
      Notification.requestPermission().then((permissionResult) => {
        if (permissionResult === 'granted') {
          console.log('Can show notifications')
        }
      })
    })
  </script>
</body>

After clicking "Show Notification", the browser will ask you if you want to allow notifications from this site or not.

If you click "Allow", you will see "Can show notifications" logged into your console.

After getting the permission to show notifications, you can start showing notifications using service workers.

Note that installing a service worker on your site is needed for listening to push events and showing notifications.

You can think of a service worker as JavaScript code that runs in the background. This means, the code in service workers can run even if your site isn't loaded or if the browser's window is closed—that's all you need to know about service workers for this tutorial, but you can learn more on MDN.

To use a service worker, you have to add it and then register it.

To add it, add a new empty file in your root directory and call it sw.js (or any name you want).

And then register it using this:

navigator.serviceWorker.register('/sw.js')
  .then(registration => {})

I'm using .then here because registering a service worker returns a promise. When that promise is resolved, it gives us the registration object, which we will use to subscribe the user and display notifications.

To display a notification, you need to call registration.showNotification(title, options).

So, let's update our code to use the registration object.

const button = document.querySelector('.show-notification-button')

button.addEventListener('click', () => {
  navigator.serviceWorker.register('/sw.js')
    .then((registration) => {
      Notification.requestPermission().then((permissionResult) => {
        if (permissionResult === 'granted') {
          registration.showNotification(
            'My first notification',
            { body: 'More details about this notification' }
          )
        }
      })
    })
})

If you click the "Show Notification" button, you will see the notification displayed like this:

Here's a quick summary of how that worked:

We listened to the button click event.
When the button is clicked, we accessed the registration of the service worker.
Once the promise is resolved and we have the registration object, we request the notification permission.
If the user allowed notifications, we call showNotification on the registration object to show the notification with whatever details we want.

The service worker and the push event

It's not useful to show a notification statically from the client. We should instead show it when we receive a push message. Push messages are sent from a server to the subscribed client.

When the server sends the client a push message, the service worker will trigger an event called push. In that event, we can access the message that was sent by the server to the client to display the notification.

Before building that server app, we can test the push event from the Chrome's dev tools.

To find that, open up the dev tools, go to the "Application" tab, then click on "Service Workers" from the left sidebar, then you should see some information about your registered service worker. Among other things, you should see an input with a button labelled "Push". If you click the "Push" button, it will trigger the push event on this service worker with the text entered in the input.

To test that, you need to add the push event listener to your service worker file, which we named sw.js.

// sw.js
self.addEventListener('push', (event) => {
  const data = event.data
  const message = data.text()
  console.log('message:', message)
})

If you click the push button from the dev tools, you will see the message you entered in the input logged into the browser's console.

But instead of logging it, you can display it in a notification.

// sw.js

self.addEventListener('push', (event) => {
  const data = event.data
  const message = data.text()
  self.registration.showNotification(message)
})

So now we understand what the push event is for and how to display a notification from it. Next, we will see how to subscribe a user to our push notifications, and then how to send notifications from the server app that we will build.

How does your server know what client to send the notification to

The server needs to know information about the client it needs to deliver the notification to. To get that information, you need to subscribe the user first. After you subscribe the user, you will get an object called ‌PushSubscription that contains all the needed information about the client you want to send the notifications to.

The important piece of data in that PushSubscription object is the endpoint field. This field contains a url that is unique to that client. By client I mean the browser that the user used to subscribe to the notifications—remember, a single user can have multiple clients (browsers).

In the server app, we can use that endpoint to send any data we want to the associated client. You will see how in a bit.

How to make sure it's secure

Imagine that someone has stolen that endpoint. Does this mean any one can send any message to the associated client?

Yes if we don't make it secure using the ‌application server keys.

The Application server keys consist of two keys: public and private keys. We use the private key on the server app side to sign the message we want to send, and then use the public key on the client side to unlock it to access its data.

Note that the application server keys are sometimes called the VAPID keys (Voluntary Application Server Identity).

Actually, the usage of these keys is required by some browsers, like Chrome. So, we have to use them to make the notifications work in all browsers.

The nice thing about these keys is that generating and using them is a one-time task. And you can get them either using this site: https://web-push-codelab.glitch.me/ or using this CLI tool.

The important thing is that you should hide the private key from the user. This key is going to be part of your server app, and you can hide it by adding it to your environment variables so you won't push it with your code.

Subscribe the user to your notifications

To subscribe a user, you need to call this function:

registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: YOUR_PUBLIC_KEY
})

This function takes an object with two fields: userVisibleOnly and applicationServerKey.

The applicationServerKey takes the public key you generated above.

The userVisibleOnly is a boolean that indicates whether the received message should be shown to the user with a notification or be a silent push. Some browsers like Chrome does not allow silent pushes because the developer might do malicious things like tracking the user's location without the user knowing. So this field should always be true.

This function returns a promise; when it's resolved, it gives us the PushSubscription object, which we will use as the identifier to the client we want to send push notifications to.

So let's update our code to include the subscription code:

const button = document.querySelector('.show-notification-button')

button.addEventListener('click', () => {
  navigator.serviceWorker.register('/sw.js')
    .then((registration) => {
      Notification.requestPermission().then((permissionResult) => {
        if (permissionResult === 'granted') {
          registration.pushManager.subscribe({
            userVisibleOnly: true,
            applicationServerKey: YOUR_PUBLIC_KEY
          }).then(pushSubscription => {
            console.log('pushSubscription', JSON.stringify(pushSubscription))
          })
        }
      })
    })
})

This code is starting to look messy with all these nested then callbacks. To clean it up, we can update it to use async/await.

const button = document.querySelector('.show-notification-button')

button.addEventListener('click', async () => {
  const registration = await navigator.serviceWorker.register('/sw.js')

  const permissionResult = await Notification.requestPermission()

  if (permissionResult !== 'granted') {
    return
  }

  const pushSubscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: YOUR_PUBLIC_KEY
  })

  console.log('pushSubscription', JSON.stringify(pushSubscription))
})

Next, let's test what we have by clicking "Show Notification". If everything went correctly, then we should see a stringified version of the pushSubscription object logged into the browser's console.

This is the value that you need to store in your server's app for that user. As I explained earlier in this article, it's up to you to decide how it should be associated with the user of your app. You might need to store it in the users table in your database. But for simplicity, I'll just copy the logged string from the console and use it directly in the server app that we'll build next.

Set up a simple Node Express app

You can build the server app using any language and framework you want. For this tutorial, I'm going to stick with JavaScript and build it using Node and Express.

First, create a new folder for the server. For this example I named it web-push-server.

Then quickly generate a package.json file using:

npm init -y

Then install express:

npm install express

And then create a new JavaScript file in the root directory and name it index.js.

Typically, sending a push message would happen after some action on the server. For example, send a notification message to the user when they receive a reply from other users.

For simplicity, I'll just send a notification message when we hit the /send endpoint. This endpoint will accept the message title through a query string called message.

// index.js

const express = require('express')

const app = express()
const port = 3000

const pushSubscription = JSON.parse(YOUR_PUSH_SUBSCRIPTION_STRING)

app.get('/send', (req, res) => {
  const message = req.query.message || ''
  res.end('Sending message: ' + message)
})

app.listen(port, () => {
  console.log(`web-push-server listening on port ${port}`)
})

Before running the app, replace ‌YOUR_PUSH_SUBSCRIPTION_STRING with the string you logged into the browser's console for the pushSubscription object. Remember, it will be different for each client that subscribes to your notifications.

Now if you run the app (with node index.js) and go to /send?message=Hi, you will see this displayed on the page.

If you see this, then our little server is working and we can move on to the next step to send a push message instead of just showing the message on the page.

Send the notification with the Web Push library

As I mentioned earlier in this article, to send the notification, you need to send a request to the endpoint included in the PushSubscription object. Instead of handling this ourselves, we can use the web push library created for that.

Pick the one for the language you are using in your server from this list: https://github.com/web-push-libs/. For this example, we need the node one.

First, let's install it.

npm install web-push

Then, let's import it and use it in our /send end point.

// index.js

const express = require('express')
const webpush = require('web-push')

const app = express()
const port = 3000

const pushSubscription = JSON.parse(YOUR_PUSH_SUBSCRIPTION_STRING)

app.get('/send', (req, res) => {
  const message = req.query.message || ''
  webpush.setVapidDetails(
    'mailto:youremail@example.com',
    YOUR_PUBLIC_KEY,
    YOUR_PRIVATE_KEY
  )
  webpush.sendNotification(
    pushSubscription,
    JSON.stringify({ message })
  )
  res.end('Sending message: ' + message)
})

app.listen(port, () => {
  console.log(`web-push-server listening on port ${port}`)
})

I did two things here. First, I called webpush.setVapidDetails to set the VAPID keys. It takes three parameters: your email address, the public key, and the private key—make sure to replace them with your values. I'll explain what this email is for in a little bit.

And then I send the notification using webpush.sendNotification. It takes two parameters: the pushSubscription object, and the message I want to send. In this example, I'm sending it as a stringified JSON so I can include more data into it.

Display the notification message on the push event

If you still have the code for testing the push event in sw.js, then you should see the notification displayed when you hit the /send endpoint on your server. However, it will be displayed as a stringified JSON. To fix that, we need to update the code to accept it as a JSON value (using data.json()), and then take the message value from it.

// sw.js

self.addEventListener('push', (event) => {
  const data = event.data
  const pushMessage = data.json()
  event.waitUntil(
    self.registration.showNotification(pushMessage.message)
  )
})

Another new thing you may have noticed here is the use of event.waitUntil. This function takes a promise to wait for it to resolve—note that self.registration.showNotification returns a promise. We need to wait for that because the browser might terminate the service worker before showing the notification. This can happen because we don't have control over when the browser wakes or terminates the service worker. But with event.waitUntil we can force it to wait and keep the service worker running until we display the notification.

To test it, go to the /send endpoint with some message in the query string. Once it's loaded, you will see the notification displayed on your device.

🎉 Awesome! You now have a working example for adding web push notifications to a site.

There are still two things I haven't talked about in this article. So keep reading!

The push service

An important thing to understand here is that your server doesn't send the push message directly to the user's browser. Instead it sends it to a web service controlled by your browser's vendor called the Push Service.

Each browser vendor uses a different push service. The main responsibility of the push service is to take the push request (which we sent using the web-push library), authenticates it using the public and private keys, and then sends it to the appropriate client.

Note that the push service queues the incoming messages if the user's browser is offline, and then it sends it to the user's browser when it's online.

We as developers don't have control over how the push service works or which one to use in the browser. However, all browsers have a standardized request spec called the web push protocol request. The push messages will work as long as they follow that request spec—using the web-push library saves us from all that work.

In the above code, we had to provide an email when sending the push message. That email is provided to the push service in case it needs to contact the sender.

Web push on mobile devices

The code we wrote in this article should work on mobile devices as well. However, for apple devices with iOS/iPadOS, you should add the site to the home screen and make sure you have display set to standalone or fullscreen in your manifest.json. For more information, read the apple's doc.

For more details

This article covers the basic workflow of adding web push notifications to your site. This is almost all you need to know to use it for any web app you have; however, there are things that I haven't talked about in this article, like customizing the behavior and the UI of the displayed notification. If you need to get into more details, check out this list of in-depth articles on web.dev.

Thanks for Reading ❤️! Follow me on Twitter for updates about my latest blog posts, video tutorials, and some cool web dev tips. Let's be friends!

Building a SolidJS App With SolidStart From Scratch

Taha Shashtari — Sat, 29 Apr 2023 07:26:39 +0000

So you've learned SolidJS and built a bunch of demos, but you haven't created a real-world application with it yet.

If that's you, and you want to learn how to use the SolidStart framework to build a server-side rendered application that's connected to a GraphQL server to load and store data, then this tutorial is for you.

In this tutorial, you'll learn how to create a new project, add pages, implement authentication, connect to a GraphQL server, and style with TailwindCSS.

Prerequisites

In this tutorial I assume that you know the basics of SolidJS and you've at least skimmed through the SolidStart docs.

If you haven't used SolidJS before, I encourage you to check the official tutorial first, and then continue here.

What are we going to build?

To focus on the concepts and the workflow of building a SolidStart app, we'll build a simple Todo app.

The app will have three pages: login page, signup page, and the homepage. The homepage will contain the list of todos the user has. The user should also be able to add new todos, toggle todos, and delete todos.

It's a good idea to check the code on GitHub before you start the tutorial (but it's optional).

The GraphQL server

I've already created the backend project for this app. So all you need to know is the url of the GraphQL server.

To use it, you have to run it first. So you need to clone the project from GitHub and run it locally.

Ok, that was a long introduction. If you're ready, let's get started.

Create the project

First, run this from the terminal:

mkdir todoapp-solid && cd todoapp-solid
pnpm create solid

You'll see a list of starter templates. Choose with-tailwindcss.

? Which template do you want to use? › - Use arrow-keys. Return to submit.
    bare
    hackernews
    todomvc
    with-auth
    with-mdx
    with-prisma
    with-solid-styled
❯   with-tailwindcss
    with-vitest
    with-websocket

This app will use typescript and will be server-side rendered, so choose yes to both.

✔ Which template do you want to use? › with-tailwindcss
✔ Server Side Rendering? … yes
✔ Use TypeScript? … yes

Now run pnpm install to install the dependencies. And while we are at it, let's install the other dependencies that we'll use in the project.

pnpm install @urql/core cookie cookie-signature graphql graphql-tag

These dependencies are related to GraphQL and cookie parsing. I'll show you where they are used later.

Before you continue, run the project by running pnpm run dev. If you open http://localhost:3000/, you should see this in your browser.

Style the body

Let's change the default background color and text color to something else. We can do that from src/root.tsx.

Add the following classes to <Body>:

<Body class="bg-gray-900 text-gray-100 antialiased font-roboto">

Remove default nav bar links

The starter template comes with a list of nav links in the root component. We don't need them for this project. So remove these from src/root.tsx.

<!-- REMOVE THESE -->
<A class="mr-2" href="/">
  Index
</A>
<A href="/about">About</A>

Remove unneeded files

For this project, we don't need the about page or the counter component that comes with the starter template. So let's remove src/routes/about.tsx and src/components/Counter.tsx.

Add the initial markup to the homepage

Now let's update our homepage (src/routes/index.tsx) to have the basic layout of our app.

import { Component } from 'solid-js'

const Home: Component = () => {
  return (
    <div class="mt-20 w-full max-w-lg mx-auto">
      <div>TODO: Header component</div>
      <div class="mt-10 flex items-center justify-between">
        <div>
          Hey <span class="font-bold">TODO: USER NAME</span>
        </div>
        <form>
          <button class="cursor-pointer text-gray-200 hover:text-white">
            Log out
          </button>
        </form>
      </div>
      <div class="mt-2.5">
        <div>TODO: AddTodoInput component</div>
        <div class="mt-3.5">
          <div>TODO: when loading show Spinner component</div>
          <div>TODO: when todos are loaded, display them </div>
          <div>TODO: If loaded todos are empty, display empty state</div>
        </div>
      </div>
    </div>
  )
}

export default Home

To know what components we will have in this page, I marked their places with TODO: .... This way it will be easier to show you where to add them when we create them later.

Create the header component

The header component is just a component that displays the name of the app and the SolidJS logo (as a nice touch 😁).

So, in src/components create Header.tsx and put the following into it.

import { Component } from 'solid-js'

const Logo = () => {
  return (
    <>
      {/* PASTE THE LOGO SVG HERE */}
      {/* https://www.solidjs.com/assets/logo.123b04bc.svg */}
    </>
  )
}

const Header: Component = () => {
  return (
    <h1 class="text-4xl font-bold text-center flex items-center justify-center">
      <div class="mr-2.5 w-10">
        <Logo />
      </div>
      Todo App
    </h1>
  )
}

export default Header

Now let's use it on the homepage by replacing <div>TODO: Header component</div> with <Header />.

import { Component } from 'solid-js'
import Header from '~/components/Header'

const Home: Component = () => {
  return (
    <div class="mt-20 w-full max-w-lg mx-auto">
      <Header />
        {/* ... */}

If you check your browser now, you should see this:

Add the login page

Like the homepage, we'll start by adding the HTML first with some TODO notes.

To add a new page in SolidStart, just add a new component to src/routes folder. Let's name it login.tsx.

import { Component } from 'solid-js'
import Header from '~/components/Header'

const Login: Component = () => {
  return (
    <div class="min-h-screen flex flex-col justify-center items-center">
      <Header />
      <div>TODO: Show an error if username or password is incorrect</div>
      <form class="mt-5 w-full max-w-lg mx-auto flex flex-col">
        <input
          class="p-3.5 rounded-t border-b border-gray-300 text-gray-900 outline-none"
          name="username"
          type="text"
          placeholder="Username"
          required
        />
        <input
          class="p-3.5 rounded-b text-gray-900 outline-none"
          name="password"
          type="password"
          placeholder="Password"
          required
        />
        <button class="mt-2.5 py-2.5 rounded bg-blue-500 hover:bg-blue-600">
          Log in
        </button>
      </form>
      <div class="mt-5">
        Don't have an account?
        <a class="text-blue-400 ml-1" href="/signup">
          Sign up here
        </a>
      </div>
    </div>
  )
}

export default Login

If you go to the login page (http://localhost:3000/login), you should see this:

Add the signup page

It should be similar to the login page.

Create src/routes/signup.tsx and put the following:

import { Component } from 'solid-js'
import Header from '~/components/Header'

const Signup: Component = () => {
  return (
    <div class="min-h-screen flex flex-col justify-center items-center">
      <Header />
      <form class="mt-5 w-full max-w-lg mx-auto flex flex-col">
        <input
          class="p-3.5 rounded-t border-b border-gray-300 text-gray-900 outline-none"
          name="name"
          type="text"
          placeholder="Name"
          required
        />
        <input
          class="p-3.5 border-b border-gray-300 text-gray-900 outline-none"
          name="username"
          type="text"
          placeholder="Username"
          required
        />
        <input
          class="p-3.5 rounded-b text-gray-900 outline-none"
          name="password"
          type="password"
          placeholder="Password"
          required
        />
        <button class="mt-2.5 py-2.5 rounded bg-blue-500 hover:bg-blue-600">
          Sign up
        </button>
      </form>
      <div class="mt-5">
        Already have an account?
        <a class="text-blue-400 ml-1" href="/login">
          Log in here
        </a>
      </div>
    </div>
  )
}

export default Signup

If you go to http://localhost:3000/signup, you should see this in your browser:

Use client-side routing with `<A />`

Right now, we are using the native <a></a> to link to other pages. It works fine, but when the user clicks it, it makes a full request (MPA-style) to go to the linked page.

We can improve that by switching it to the enhanced <A/> version to redirect to the page on the client (SPA-style). It makes the user experience faster and smoother.

All you have to do is just replace <a> with <A> after importing it with import { A } from 'solid-start'.

So, let's update the login page and the signup page to use it.

<A class="text-blue-400 ml-1" href="/signup">
  Sign up here
</A>

Signup:

<A class="text-blue-400 ml-1" href="/login">
  Log in here
</A>

How are we going to implement authentication?

Authentication is a big topic that deserves a series of blog posts. But to keep things simple, I'll explain how it works in this app in general, and then you can understand the details in the code on your own (which I encourage if you want to improve your development skills).

We will use JWT tokens for authentication. If you are not familiar with it, I recommend learning about it before continuing. (I wrote a blog post about here: Understand JWT in 3 minutes.)

Here's a quick overview of how we are going to handle authentication in this app:

The user logs in by providing their username and password
We send the username and the password to our GraphQL server
The GraphQL checks if they are valid (by comparing them to what's stored in the database)
Then, if they are valid, the GraphQL server generates a JWT token and returns it to our app in the response
Then, we'll be using this token by embedding it into the headers of every GraphQL query and mutation we send

Now this looks straightforward, but the complication comes when we want to store that token on the client side (so the user doesn't have to login every time they close the app).

We need a place where both the server and the browser can access the token. The first thing comes to mind is cookies, which is correct. But storing it in regular cookies opens us to some security issues. The best way to avoid these issues is to store it in an http-only cookie – which is a cookie that can only be accessed from the server.

Now the question is: how can the browser access the token then?

Remember, we need the browser to access the token to send queries and mutations from the browser as well (i.e. AJAX requests).

The answer is by proxying the browser requests through our app's API routes (which is run by our app's server). So instead of sending the GraphQL request directly to the GraphQL server url, we send it through an internal endpoint on our server that can access the token from the cookie. Then it takes the token, put it on the request headers, and then forwards the request to the real GraphQL server.

The internal server endpoint can be easily created with SolidStart's API Routes.

This is a brief explanation of how the authentication in this app will work. Since it's beyond the scope of this tutorial to explain how the authentication code works, I'll just show you how to add the authentication code and how to use it.

Add the GraphQL client

You can use any GraphQL client you want. For this project, I will use URQL.

We will be using the client in multiple places, so let's add a module that we can import to get an instance of the client.

Let's create it in a folder named lib inside src. So, create src/lib/urqlClient.ts and put the following into it (I will explain what it contains below).

import { createClient } from '@urql/core'
import { isServer } from 'solid-js/web'

let token = ''

export function setToken(newToken: string) {
  token = newToken
}

export const urqlClient = () => {
  return createClient({
    url: isServer ? import.meta.env.VITE_GRAPHQL_URL : '/api/graphql',
    fetchOptions: () => {
      return {
        headers: {
          authorization: token || ''
        }
      }
    }
  })
}

This module exports two functions: setToken and urqlClient.

In the beginning, when the app loads, the token will not be available to the client, but it might be stored in the cookie. So, we need a way to set it once it's available – that's what setToken is for.

urqlClient is used to get an instance of the GraphQL client. It might be used from the browser or the server. If it's used in the server, then we need to set its url directly to the GraphQL server (because no need to use the proxy in the server since it has access to the http-only cookie).

Note how we are using import.meta.env.VITE_GRAPHQL_URL to get the url from environment variables, which we store in .env, which we'll create in a bit.

If the GraphQL client is used from the browser, then we should set its url to the proxy endpoint, in this case it will be /api/graphql (you can name it whatever you want, but it has to match path of API route in routes folder).

Add `.env`

It's always a good practice to store sensitive data as environment variables. So let's create .env in the root directory and put this into it:

VITE_GRAPHQL_URL=http://localhost:4000/graphql
VITE_COOKIE_TOKEN_KEY=solid-todoapp-token
VITE_COOKIE_SECRET_KEY=secret

We can easily access them any where in the app with import.meta.env.YOUR_VAR_NAME.

Add the GraphQL proxy API route

Since we have used the /api/graphql as the proxy url, then we need to create the API route in src/routes/api/graphql.ts.

Here's the code to put into it. You don't need to understand how it works, but just know that it forwards any GraphQL request coming from the browser to the real GraphQL server url (after putting the JWT token to its headers).

import { APIEvent, json } from 'solid-start'
import cookieParser from 'cookie'
import cookieSign from 'cookie-signature'

async function parseBody(request: Request) {
  const reader = request.body.getReader()
  const stream = await new ReadableStream({
    start(controller) {
      return pump()
      function pump() {
        return reader.read().then(({ done, value }) => {
          if (done) {
            controller.close()
            return
          }
          controller.enqueue(value)
          return pump()
        })
      }
    }
  })
  return await (await new Response(stream)).json()
}

function getToken(request: Request) {
  const parsedCookies = cookieParser.parse(request.headers.get('Cookie'))
  const unsigned = cookieSign.unsign(
    parsedCookies[import.meta.env.VITE_COOKIE_TOKEN_KEY],
    import.meta.env.VITE_COOKIE_SECRET_KEY
  )
  const decoded = JSON.parse(Buffer.from(unsigned, 'base64').toString('utf8'))
  return decoded.token
}

const proxyGraphqlRequest = async (request: Request) => {
  const payload = await parseBody(request)
  const token = await getToken(request)

  try {
    const resposne = await fetch(import.meta.env.VITE_GRAPHQL_URL, {
      method: 'POST',
      mode: 'cors',
      headers: {
        ...request.headers,
        'content-type': 'application/json',
        authorization: token
      },
      body: JSON.stringify(payload)
    })
    const jsonResponse = await resposne.json()
    return json(jsonResponse)
  } catch (error) {
    console.log('error', error)
  }
}

export const POST = ({ request }: APIEvent) => {
  return proxyGraphqlRequest(request)
}

Add queries and mutations

The GraphQL server for this app provides us with a list of queries and mutations that we will use to login users, signup users, add todos, update todos, etc.

Let's add them to our project under src/graphql/. All queries will go in src/graphql/queries.ts, and all mutations will go in src/graphql/mutations.ts.

Put the following into src/graphql/queries.ts:

import { gql } from 'graphql-tag'

export const CURRENT_USER = gql`
  query currentUser {
    currentUser {
      id
      username
      name
    }
  }
`

export const TODOS = gql`
  query todos {
    todos {
      id
      title
      completed
    }
  }
`

And this into src/graphql/mutations.ts:

import { gql } from 'graphql-tag'

export const SIGNUP_USER = gql`
  mutation signupUser($input: SignupUserInput!) {
    signupUser(input: $input) {
      status
    }
  }
`

export const LOGIN_USER = gql`
  mutation loginUser($username: String!, $password: String!) {
    loginUser(username: $username, password: $password) {
      token
    }
  }
`

export const UPDATE_TODO = gql`
  mutation updateTodo($input: UpdateTodoInput) {
    updateTodo(input: $input) {
      status
    }
  }
`

export const DELETE_TODO = gql`
  mutation deleteTodo($todoId: ID) {
    deleteTodo(todoId: $todoId) {
      status
    }
  }
`

export const ADD_TODO = gql`
  mutation addTodo($input: AddTodoInput!) {
    addTodo(input: $input) {
      id
      title
      completed
    }
  }
`

Actions in SolidStart

SolidStart gives us a neat way to handle form submissions. Form submissions can either be done on the browser side (AJAX) or on the server side.

What determines which one to use is the function you use to create the action. createServerAction$ for server submissions, and createRouteAction for browser submissions.

Calling either one returns an array of two values. The first one contains the status of the action (like if it's pending, or if it has errors). The second value contains the function that runs the action.

To make this even better, we can access <Form /> off of the second value, which is an enhanced version of the form element. Using it will run the action once the form is submitted.

Integrate the signup form

To integrate the signup form, we need to create an action for the server to send a GraphQL mutation to create a new user. Then, we'll replace the current <form> with the <Form /> component that we got from the action.

Here's the full code of the signup page after the integration:

import { Component } from 'solid-js'
import { A } from 'solid-start'
import { createServerAction$, redirect } from 'solid-start/server'
import Header from '~/components/Header'
import { SIGNUP_USER } from '~/graphql/mutations'
import { urqlClient } from '~/lib/urqlclient'

const Signup: Component = () => {
  const [_, { Form }] = createServerAction$(async (form: FormData) => {
    const name = form.get('name')
    const username = form.get('username')
    const password = form.get('password')

    const result = await urqlClient()
      .mutation(SIGNUP_USER, { input: { name, username, password } })
      .toPromise()
    if (result) {
      return redirect('/login')
    }
  })

  return (
    <div class="min-h-screen flex flex-col justify-center items-center">
      <Header />
      <Form class="mt-5 w-full max-w-lg mx-auto flex flex-col">
        <input
          class="p-3.5 rounded-t border-b border-gray-300 text-gray-900 outline-none"
          name="name"
          type="text"
          placeholder="Name"
          required
        />
        <input
          class="p-3.5 border-b border-gray-300 text-gray-900 outline-none"
          name="username"
          type="text"
          placeholder="Username"
          required
        />
        <input
          class="p-3.5 rounded-b text-gray-900 outline-none"
          name="password"
          type="password"
          placeholder="Password"
          required
        />
        <button class="mt-2.5 py-2.5 rounded bg-blue-500 hover:bg-blue-600">
          Sign up
        </button>
      </Form>
      <div class="mt-5">
        Already have an account?
        <A class="text-blue-400 ml-1" href="/login">
          Log in here
        </A>
      </div>
    </div>
  )
}

export default Signup

Integrate the login form

Let me show you the code first and explain it below.

import { Component, Show } from 'solid-js'
import { A, FormError } from 'solid-start'
import { createServerAction$, redirect } from 'solid-start/server'
import Header from '~/components/Header'
import { login } from '~/session'

const Login: Component = () => {
  const [loggingIn, { Form }] = createServerAction$(async (form: FormData) => {
    const username = form.get('username')
    const password = form.get('password')

    if (typeof username !== 'string' || typeof password !== 'string') {
      throw new FormError('Form data are not correct')
    }

    const headers = await login({ username, password })
    if (headers) {
      return redirect('/', { headers })
    }
  })

  return (
    <div class="min-h-screen flex flex-col justify-center items-center">
      <Header />
      <Show when={loggingIn.error}>
        <div class="mb-3.5 px-3.5 py-2 rounded-lg bg-red-700 text-red-50 text-sm font-medium">
          Your username or password is incorrect
        </div>
      </Show>

      <Form class="mt-5 w-full max-w-lg mx-auto flex flex-col">
        <input
          class="p-3.5 rounded-t border-b border-gray-300 text-gray-900 outline-none"
          name="username"
          type="text"
          placeholder="Username"
          required
        />
        <input
          class="p-3.5 rounded-b text-gray-900 outline-none"
          name="password"
          type="password"
          placeholder="Password"
          required
        />
        <button class="mt-2.5 py-2.5 rounded bg-blue-500 hover:bg-blue-600">
          Log in
        </button>
      </Form>
      <div class="mt-5">
        Don't have an account?
        <A class="text-blue-400 ml-1" href="/signup">
          Sign up here
        </A>
      </div>
    </div>
  )
}

export default Login

We created a server action similar to the signup page, but the main difference here is that we are not using the GraphQL client here. Instead, we are calling a login() function from a file called session.ts, which we haven't created yet.

The reason for that is because logging in involves more things that just sending a GraphQL request. For example, after the user is logged in, we need to store the token in the cookie.

We can also add other things related to authentication in session.ts, like getUser to get the current user data, and logout.

So to finish up the login page, create src/session.ts and put this into it.

import { createCookieSessionStorage, FormError, redirect } from 'solid-start'
import { LOGIN_USER } from './graphql/mutations'
import { CURRENT_USER } from './graphql/queries'
import { setToken, urqlClient } from './lib/urqlclient'

const storage = createCookieSessionStorage({
  cookie: {
    name: import.meta.env.VITE_COOKIE_TOKEN_KEY,
    secure: true,
    secrets: [import.meta.env.VITE_COOKIE_SECRET_KEY],
    sameSite: 'lax',
    path: '/',
    maxAge: 60 * 60 * 24 * 30,
    httpOnly: true
  }
})

interface LoginForm {
  username: string
  password: string
}

export const login = async ({ username, password }: LoginForm) => {
  const result = await urqlClient()
    .mutation(LOGIN_USER, { username, password })
    .toPromise()

  if (!result.data?.loginUser?.token) {
    throw new FormError('Wrong username or password')
  }

  const token = result.data.loginUser.token

  const session = await storage.getSession()
  session.set('token', token)
  return {
    'Set-Cookie': await storage.commitSession(session)
  }
}

export const getUser = async (request: Request) => {
  const session = await storage.getSession(request.headers.get('Cookie'))
  const token = session.get('token')
  if (!token) {
    return null
  }

  setToken(token)

  const result = await urqlClient().query(CURRENT_USER, {}).toPromise()

  if (!result.data?.currentUser) {
    return redirect('/login')
  }
  return result.data.currentUser
}

export const logout = async (request: Request) => {
  const session = await storage.getSession(request.headers.get('Cookie'))
  return redirect('/login', {
    headers: {
      'Set-Cookie': await storage.destroySession(session)
    }
  })
}

Add route guards

By route guards I mean preventing logged-in users from going to the login and the signup pages and preventing guest users from going to the homepage.

To do this, we need to fetch the user using getUser() from src/sessions.ts, and see if it returns the user data. If it doesn't, then it means the user is not logged in.

To make redirection works, we need to fetch the user before the page is rendered, in other words, fetch the user on the server side.

We can easily do that using createServerData$ in routeData.

Let's use this on the homepage so that it redirects the user to the login page if not logged in yet.

Add this at the top of src/routes/index.tsx above const Home: Component = () => {:

import { Component } from 'solid-js'
import { redirect } from 'solid-start'
import { createServerData$ } from 'solid-start/server'
import Header from '~/components/Header'
import { getUser } from '~/session'

export function routeData() {
  const user = createServerData$(async (_, { request }) => {
    const user = await getUser(request)

    if (!user) {
      throw redirect('/login')
    }
    return user
  })

  return { user }
}

You can now test that in your browser. Try to go to http://localhost:3000, and you should be redirected http://localhost:3000/login automatically.

Note that you should be logged out first, which you can do manually by clearing the cookies – we'll implement the logout button later.

Now let's add the login and the signup route guards.

The login route guard is similar to the homepage except we redirect to the homepage if the user is logged in.

Update src/routes/login.tsx:

import { Component, Show } from 'solid-js'
import { A, FormError, useRouteData } from 'solid-start'
import {
  createServerAction$,
  createServerData$,
  redirect
} from 'solid-start/server'
import Header from '~/components/Header'
import { getUser, login } from '~/session'

export function routeData() {
  return createServerData$(async (_, { request }) => {
    if (await getUser(request)) {
      throw redirect('/')
    }
    return {}
  })
}

const Login: Component = () => {
  const user = useRouteData<typeof routeData>()
  user()
  // ...

An important thing to note here is that we had to call user() at the beginning of the component. We need to do that because the route data doesn't get fetched until we call it explicitly.

Let's add the same thing to the signup page.

Update src/routes/signup.tsx:

import { Component } from 'solid-js'
import { A, useRouteData } from 'solid-start'
import {
  createServerAction$,
  createServerData$,
  redirect
} from 'solid-start/server'
import Header from '~/components/Header'
import { urqlClient } from '~/lib/urqlclient'
import { getUser } from '~/session'
import { SIGNUP_USER } from '../graphql/mutations'

export function routeData() {
  return createServerData$(async (_, { request }) => {
    if (await getUser(request)) {
      throw redirect('/')
    }
    return {}
  })
}

const Signup: Component = () => {
  const user = useRouteData<typeof routeData>()
  user()
  // ...

Integrate log out

We have a log out button on the homepage, but it doesn't do anything yet. Let's fix that by adding a server action that calls logout() from src/session.ts.

So, update src/index.tsx:

// ...
const Home: Component = () => {
  const [, { Form }] = createServerAction$((f: FormData, { request }) =>
    logout(request)
  )
  // ...

Also, update the form element to use <Form />.

Display the user name on the homepage

We are already fetching the user on the homepage, but we are not using it yet.

Get the user data from the route by adding this:

const Home: Component = () => {
  const { user } = useRouteData<typeof routeData>()
  // ...

And then display the user name in place of TODO: USER NAME:

<span class="font-bold">{user()?.name}</span>

Create the Spinner component

This is a simple SVG component we will use for showing a loading indicator.

Create src/components/Spinner.tsx.

export default function Spinner() {
  return (
    <div class="w-full">
      {/* By Sam Herbert (@sherb), for everyone. More @ http://goo.gl/7AJzbL */}
      <svg
        viewBox="0 0 38 38"
        xmlns="http://www.w3.org/2000/svg"
        stroke="currentColor"
      >
        <g fill="none" fill-rule="evenodd">
          <g transform="translate(1 1)" stroke-width="2">
            <circle stroke-opacity=".5" cx="18" cy="18" r="18" />
            <path d="M36 18c0-9.94-8.06-18-18-18">
              <animateTransform
                attributeName="transform"
                type="rotate"
                from="0 18 18"
                to="360 18 18"
                dur="1s"
                repeatCount="indefinite"
              />
            </path>
          </g>
        </g>
      </svg>
    </div>
  )
}

Create AddTodoInput component

This component will be used to display the todo input and create the todos with ADD_TODO mutation.

Create the component file at src/components/AddTodoInput.tsx, and add this into it:

import { Component, createEffect, Show } from 'solid-js'
import { createRouteAction } from 'solid-start'
import { urqlClient } from '~/lib/urqlclient'
import Spinner from './Spinner'
import { ADD_TODO } from '../graphql/mutations'

interface AddTodoInputProps {
  refetchTodos: () => void
}

const AddTodoInput: Component<AddTodoInputProps> = (
  props: AddTodoInputProps
) => {
  const [addingTodo, { Form }] = createRouteAction(async (form: FormData) => {
    return await urqlClient()
      .mutation(ADD_TODO, {
        input: {
          title: form.get('title')
        }
      })
      .toPromise()
  })

  createEffect(() => {
    if (addingTodo.result) {
      props.refetchTodos()
    }
  })

  let inputRef: HTMLInputElement

  return (
    <Form
      class="px-5 w-full bg-gray-100 rounded-lg outline-none text-gray-900 flex items-center justify-between"
      onSubmit={(e) => {
        if (!inputRef.value.trim()) e.preventDefault()
        setTimeout(() => (inputRef.value = ''))
      }}
    >
      <input
        class="rounded-lg py-3.5 flex-1 bg-gray-100 outline-none pr-2.5"
        name="title"
        type="text"
        placeholder="What needs to be done?"
        readonly={addingTodo.pending}
        ref={inputRef}
      />
      <Show when={addingTodo.pending}>
        <div class="text-blue-900 w-8">
          <Spinner />
        </div>
      </Show>
    </Form>
  )
}

export default AddTodoInput

Two things to note here.

First, we are sending the mutation with createRouteAction instead of createServerData$ because we want to send it from the browser (AJAX).

Second, we are accepting a prop called refetchTodos. It's a function that will refetch todos after we add a new one. We will pass it from the homepage component (which we'll get to in a bit).

Create TodoItem component

This component will be used to display each todo item in the list. It will also contain the code to toggle its completed status, and the code to delete itself.

Toggling the todo will be done using UPDATE_TODO mutation. And deleting it will be done using DELETE_TODO mutation.

This component accepts two props: todo, which will contain the todo data to display, and refetchTodos, which will refetch the todos when it's toggled or deleted.

Here's the full code for the TodoItem component (src/components/TodoItem.tsx):

import { Component, createEffect, Show } from 'solid-js'
import { createRouteAction } from 'solid-start'
import { urqlClient } from '~/lib/urqlclient'
import { DELETE_TODO, UPDATE_TODO } from '../graphql/mutations'

export interface Todo {
  id: string
  title: string
  completed: boolean
}

interface TodoProps {
  todo: {
    id: string
    title: string
    completed: boolean
  }
  refetchTodos: () => void
}

const TodoItem: Component<TodoProps> = (props: TodoProps) => {
  const [deletingTodo, deleteTodo] = createRouteAction(
    async (todoId: string) => {
      return await urqlClient()
        .mutation(DELETE_TODO, {
          todoId: todoId
        })
        .toPromise()
    }
  )

  const [togglingTodo, toggleTodo] = createRouteAction(
    async ({ todoId, completed }: { todoId: string; completed: boolean }) => {
      return await urqlClient()
        .mutation(UPDATE_TODO, {
          input: {
            todoId,
            completed
          }
        })
        .toPromise()
    }
  )

  createEffect(() => {
    if (deletingTodo.result || togglingTodo.result) {
      props.refetchTodos()
    }
  })

  return (
    <div class="group flex items-center justify-between bg-gray-200 rounded-lg px-5 py-3.5 text-gray-900">
      <div class="flex items-center">
        <button
          class={
            'hover:border-blue-500 border-2 w-5 h-5 rounded-full flex items-center justify-center text-white cursor-pointer ' +
            (props.todo.completed
              ? 'bg-blue-500 border-blue-500'
              : 'border-gray-500')
          }
          onClick={() =>
            toggleTodo({
              todoId: props.todo.id,
              completed: !props.todo.completed
            })
          }
        >
          <Show when={props.todo.completed}>
            <svg style="width: 15px; height: 15px" viewBox="0 0 24 24">
              <path
                fill="currentColor"
                d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"
              />
            </svg>
          </Show>
        </button>
        <span
          class={
            (props.todo.completed ? 'line-through text-gray-500' : '') +
            ' ml-2.5'
          }
        >
          {props.todo.title}
        </span>
      </div>

      <button
        class="opacity-0 group-hover:opacity-100 text-gray-500 hover:text-gray-900"
        onClick={() => deleteTodo(props.todo.id)}
      >
        <svg style="width: 24px; height: 24px" viewBox="0 0 24 24">
          <path
            fill="currentColor"
            d="M9,3V4H4V6H5V19A2,2 0 0,0 7,21H17A2,2 0 0,0 19,19V6H20V4H15V3H9M9,8H11V17H9V8M13,8H15V17H13V8Z"
          />
        </svg>
      </button>
    </div>
  )
}

export default TodoItem

Fetch todos

Let's update routeData in src/routes/index.tsx to fetch the todos along with the user.

import { Component, createResource } from 'solid-js'
import { redirect, useRouteData } from 'solid-start'
import { createServerAction$, createServerData$ } from 'solid-start/server'
import Header from '~/components/Header'
import { Todo } from '~/components/TodoItem'
import { TODOS } from '~/graphql/queries'
import { urqlClient } from '~/lib/urqlclient'
import { getUser, logout } from '~/session'

export function routeData() {
  const user = createServerData$(async (_, { request }) => {
    const user = await getUser(request)

    if (!user) {
      throw redirect('/login')
    }
    return user
  })

  const [todos, { refetch }] = createResource<Todo[]>(async () => {
    const { data } = await urqlClient().query(TODOS, {}).toPromise()
    return data.todos
  })

  return { user, todos, refetchTodos: refetch }
}

Note how we are also returning refetchTodos from it.

Next, let's update the component to use the new fields.

const Home: Component = () => {
  const { user, todos, refetchTodos } = useRouteData<typeof routeData>()
  todos()
    // ...

Display AddTodoInput component

Our next step is to use <AddTodoInput /> component, which we've already created.

Import it, and replace <div>TODO: AddTodoInput component</div> with:

<AddTodoInput refetchTodos={refetchTodos} />

Adding new todos should work, but you wouldn't see what's added because we haven't displayed the todos yet. This is for the next step.

Display todos

Displaying todos has three states: loading todos, showing an empty state when the todo list is empty, or displaying the todo items.

To display the loading indicator, replace <div>TODO: when loading show Spinner component</div> with:

<Show when={todos.loading}>
  <div class="mt-10 flex items-center justify-center text-xl font-medium">
    <div class="w-5 mr-2.5">
      <Spinner />
    </div>
    Loading Todos
  </div>
</Show>

When we have todos for the user, display them with <TodoItem /> component. So, replace <div>TODO: when todos are loaded, display them </div> with:

<Show when={!todos.loading && todos() && todos().length > 0}>
  <div class="space-y-2.5">
    <For each={todos()}>
      {(todo: Todo) => (
        <TodoItem todo={todo} refetchTodos={refetchTodos} />
      )}
    </For>
  </div>
</Show>

For the empty state, replace <div>TODO: If loaded todos are empty, display empty state</div> with:

<Show when={!todos.loading && !todos().length}>
  <div class="mt-10 text-center text-blue-50 text-opacity-40">
    Your Todo List is Empty
  </div>
</Show>

The app is ready

🎉 Congratulations! You've created a fully functioning app with SolidJS and SolidStart.

You should be able to sign up a new user, log in to the app, log out from the app, add todos, toggle todos, and delete todos.

Thanks for Reading ❤️! Follow me on Twitter for updates about my latest blog posts, video tutorials, and some cool web dev tips. Let's be friends!

Introduction to testing

Taha Shashtari — Mon, 17 Apr 2023 23:01:14 +0000

All programmers do testing the very first time they write code in their lives. After you add or modify some line of code, you head to the browser to see the changes. Sometimes, you want to check the new feature you added, and other times you just want to see if something broke after you modified something in your code.

That kind of testing is called manual testing.

If something is called manual, it means there should be an automated version. And there is, and it's called automated testing.

With automated tests, you don't need to go manually testing your changes in the browser most of the time; there should be a command you run to do all the testing for you.

It's easier said than done. That command is something you need to implement; and here comes the other aspect of learning programming, which is learning to write tests.

Functional vs. Non-functional tests

In this article I'm talking about functional tests. Functional tests are the tests that ensure that your code is working as expected. It's testing the behavior of your software—does it do what it should do?

Non-functional tests, on the other hand, are for testing the other aspects of the software, such as testing performance and security.

Great benefits of writing automated tests

The two biggest benefits of writing automated tests are: detecting bugs and refactoring.

Detecting bugs is basically checking if you broke the code after certain changes—the same reason you do manual testing.

Refactoring is also checking if you broke the code but after improving the code. There are many times where you think about improving the design of the code, but you are reluctant to do that because you might break something. With good tests, you don't have to worry about this because you will know if you broke something while refactoring it.

So a common thing developers with tests would do is writing the code the fastest way possible just to make the tests pass, and then refactoring it to make it look better.

Types of tests

If you had ever read anything about testing, it's likely that you have come across these terms: unit testing, integration testing, end-to-end testing, acceptance testing, and the list goes on and on.

Interestingly, each of these types tends to have a different definition. Explaining each one in detail will require a whole article for each one. But in my experience, understanding the following three types of tests the way I (and many others) look at them will save you a lot of time and confusion in the future.

Unit tests

Unit tests are the most basic type of tests. They form the majority of the tests in your code. Some see units as the low-level stuff in your code, like objects and functions. Others, including me, see each unit as a single test that tests some specific behavior in the software. That test might use multiple objects and functions to achieve some goal.

An example would be a test that tests the parsing of CSV string. That test might use multiple objects and functions to achieve that, but it's still a single test that tests a behavior of my software.

Integration tests

Integration tests test the integration between two standalone parts of the system. Some look at integration tests as a way to test the integration of multiple objects and functions in the same system. Others, including me, look at it as the integration between the software's code and other services.

An example would be testing the integration between your app and a third-party payment service. In this case, your app works alone, and the payment service works alone, but does the integration between them work as expected in the context of your app?

End-to-End tests

If unit tests are for testing the internals of your software, and integration tests are for testing the integration with other parties, how can you test if your whole app works as a whole?

That's what end-to-end tests are for. They are the slowest kind of tests. They should run the same way your user would use the app: go to a specific url with some input, and then see something on the page (or get a specific response from that endpoint).

There are tools for that kind of testing. These tools can literally open a new instance of the browser, go to a specific url, and inspect the results on the screen—you can literally see that process happening in front of you, unless you are using headless browser testing.

The speed of tests

The speed of your tests are based on the type of tests you are running and how they are implemented. They can be as fast as a few hundred milliseconds or as slow as several hours.

Unit tests are usually the fastest because they don't need to wait for a response from some external server or run the app in the browser.

Integration tests can be as fast as unit tests or can be slower. This depends on how you implement them: if you are mocking the third-party service (I'll talk about mocks in a little bit), then they will be fast. If you don't mock them, then the speed depends on the performance of that third-party interaction.

End-to-end tests are the slowest because they need to run as if the app is in production. You need to wait for requests and third-party services to complete before seeing the results of your tests.

A good practice is to split your test suites in types so you can run each one separately. A general rule of thumb is to run unit tests on every change because they are the fastest; run integration tests multiple times in an hour; run end-to-end tests a couple times per day to make sure that the whole system works as expected.

Mocking

Mocking is a very a big topic if I want to get into its details. But in its essence, mocking is replacing an element in your code (like object or function) with a fake version.

There are multiple reasons why you would need to do that. One reason is performance. If your tests need to talk to an external service, you can replace that external service with a mock so you don't have to make an actual request, and instead use the mock to get some response.

Some people use mocking for isolating the thing they are testing from the rest of the app—this is called the Mockist testing style. Some people don't like this approach, but it's a valid one used by many great developers.

As I mentioned above, getting into the details of mocking is beyond the scope of this article. So all you need to know is that mocking is a fake version of some element in your tests—most testing tools support creating them.

Test-driven development

You probably heard the term TDD (Test-driven development). TDD is just one way to write and run your tests. From its name, it's a way to derive your code through tests, which means you write tests first and then the code to make it pass.

It might feel awkward at first, but it's actually a good thing to do for two main reasons. Writing the test first ensures you have a test for each code you implement—if you don't do this, you might forget to write the test after writing the actual code, or might miss some cases.

Another reason TDD is good is because it forces you to think how your code will work and look like before implementing it, which would help you make better upfront design decisions—some find this true and some don't, but personally I find it useful in that regard.

TDD might not be for everyone. You don't have to use it if you don't like it. I think of it as one style of writing tests.

Tools for writing tests

I don't think the tool is the most important thing here. The JavaScript ecosystem has a good number of testing tools, like Jest, Mocha, or Vitest, which is what I use these days.

The above tools are mainly used for unit and integration testing. At the time of this writing, Cypress and Playwright are the most popular tools for end-to-end testing.

Any of these tools would do the work. The important thing here is to learn how to write good tests—and that only comes with practice.

Code coverage

Code coverage is the percentage of how much your code is covered with tests. Some aim for 100% coverage. I find this almost impossible to have; instead, you should aim to cover the critical, major parts of the behavior of your software.

For example, you don't have to test all the getters and setters of an object if they work as simple getters and setters. Instead, test the thing that really matters to how your software pieces should behave. For example, test a setter of an object if it runs some validation before setting a value.

So the question of how much coverage I should have in my tests is not easy to answer. It usually depends on what phase the software is in and what the software is really trying to do.

A simple example

My goal in this article is not to show you how to write tests (I might have more articles on these in the future), but rather to show you the whats and the whys of testing.

Having said that, I think it would be a good idea to show you a quick example of what testing looks like in the code.

In this simple example, I'll write a function that adds two numbers (the classical example of testing), and I'll write a test for it.

I'll use Vitest in this example, but you can use whatever tool you like.

You can check their docs to see how to install it. After you install it, create a new test file called calculator.test.js.

// calculator.test.js

import { describe, it, assert } from 'vitest'
import { add } from './calculator'

describe('calculator', () => {
  it('add two numbers', () => {
    assert.equal(add(2, 2), 4)
  })
})

This code tests a function called add in a module called calculator. That function takes two arguments to add. So, it tests if adding 2 and 2 returns 4.

To make it pass, you have to create the calculator module—see how I wrote the test before the code, that's basically what TDD is.

// calculator.js

export function add(a, b) {
  return a + b
}

Now, if you run the test it should pass.

You can check the docs of the tool to see how to run the tests. In my example with Vitest, I had to add a new script to package.json called test. And when I run npm run test, it would run all of my tests.

Conclusion

Testing is an important part of writing good code. With it, you can detect bugs and refactor your code. Not only that, but it also helps you think about how your software should behave, especially when you use TDD.

Learning how to write good tests only comes with practice. It's okay if you find it difficult to test something at first, but if you keep practicing, you will eventually find your own testing style and what works and what doesn't.

Thanks for Reading! Follow me on Twitter for web dev tips. Let's be friends!

DEV Community: Taha Shashtari

Make your JavaScript more readable with named parameters

How the function is defined

Default values

A common pitfall

One parameter

All the good things

🔗 Let's stay connected:

Strategy pattern is better when done with functions

The OOP way

The functional way

With functions, you pass what you just need

That's why functions are better for the Strategy pattern

🔗 Let's stay connected:

Why you shouldn't use async and defer in the same script tag

What are async scripts useful for?

What happens if you use both async and defer on the same script?

🔗 Let's stay connected:

Why the number of Gleam programmers is growing so fast?

It's small and simple

Nice syntax

It's explicit

Labelled arguments

Pipelines

Powerful flow control

Developer friendly

Friendly community

Start learning Gleam

🔗 Let's stay connected:

Mastering closures in JavaScript

What is scoping?

Static (lexical) vs. dynamic scoping

let and const vs. var

Access direction

It also works for functions

Returning a function from another function

One more step to create a closure

Closures can also modify outer variables

You can return multiple closures from a function

Why closures?

Example 1: Encapsulation

Example 2: Partial application

Example 3: Validation functions

Example 4: Throttling

Example 5: Memoization

Conclusion

There are countless applications of closures. Are there any that haven't been mentioned in this article? Please share them in the comments section.

🔗 Let's stay connected:

Software design patterns and principles are not the goal

Writing easy-to-change code is not easy!

An example that doesn't need a design pattern

An example that needs a design pattern

How to know what pattern to use?

When to look for patterns to use in your code?

The best way to implement a pattern

It's not about using design patterns or principles

A practical advice

🔗 Let's stay connected!

[Video] Understand How to Submit Forms

🔗 Let's stay connected!

[Video] Introduction to Backend for Frontend Developers

🔗 Let's stay connected!

[video] Flip Card in CSS (Like Apple)

How to Add Web Push Notifications to Your Web App

What is a push notification?

A general overview of the web push notification workflow

Display a test notification

The service worker and the push event

How does your server know what client to send the notification to

How to make sure it's secure

Subscribe the user to your notifications

Set up a simple Node Express app

Send the notification with the Web Push library

Display the notification message on the push event

The push service

Web push on mobile devices

For more details

Building a SolidJS App With SolidStart From Scratch

Prerequisites

What are we going to build?

`let` and `const` vs. `var`

Use client-side routing with `<A />`

Add `.env`