DEV Community: Joona Piirainen

Functional Dependency Injection

Joona Piirainen — Sat, 09 Apr 2022 17:00:59 +0000

Let's talk about functions! We all love functions, right? Well at least I do, I write tens of them every day! I have been a TypeScript programmer in my day job for the last 1,5 years, and would like to share some practices I have seen work, and others that.. well.. suck.

Today I want to talk about the problem of global configuration in a backend application.

Global configuration

Typically you see global configuration represented as an ordinary object. When I say global configuration this can mean constants like port, host and also system wide dependencies such as a database connection or even some state, such as the currently active user.

type Config = {
  // configuration constants
  port: number;
  host: string;
  // so called "dependencies"
  db: { getUserByUserName: (userName: string) => Promise<User> };
  logger: { info: (s: string) => void };
  // state variables
  currentUserName: Option<string>;
};

const config: Config = {
  port: process.env.PORT ?? 3000,
  host: process.env.HOST ?? "localhost",
  db: { getUserByUserName: () => Promise.resolve({ name: "some user" }) },
  logger: { info: console.log },
  currentUserName: O.some("some user"),
};

The most naive and unfortunately the most common way to consume global dependencies is something along the lines of the following code snippet.

const fetchUserNaive = (): Promise<Option<User>> => {
  const { db, logger, currentUserName } = config;
  return pipe(
    currentUserName,
    O.fold(
      () => Promise.resolve(O.none),
      (userName) => {
        logger.info(`fetching user with userName: ${userName}`);
        return db.getUserByUserName(userName).then(O.some);
      }
    )
  );
};

const hasAuthNaive = (): boolean => O.isSome(config.currentUserName);

Why is this so bad you might ask. Well:

Function inpurity:

Pure functions (functions that only depend on it's input parameters and have no side-effects) are a lot easier to reason about and compose. Functions that read/manipulate global state are inherently impure. Yuk.

Makes program state unpredictable:

If a global configuration object is being used all over the application in a language that is not pure, there's no guarantee that the object is not being mutated. This implies that the program's behaviour can change radically from the global configuration getting mutated.

Mocking in tests becomes hard:

Providing different mock implementations for different tests is hard / error-prone.

Concurrency issues:

Not a problem in a single-threaded environment such as NodeJs, but anywhere else sharing mutable global state requires some kind of locking, which adds considerably more complexity to your code.

Code comprehension:

Code behaviour that depends on a lot of mutable global variables is hard to understand.

Luckily improving from this is relatively simple. Let me introduce you to...

Function parameters

So the idea is to not depend on any values outside of our functions parameters, this forces us to list all of the dependencies the function has. When adapted to this style the previous code becomes:

const fetchUserParams = (cfg: Config): Promise<Option<User>> => {
  const { db, logger, currentUserName } = cfg;
  return pipe(
    currentUserName,
    O.fold(
      () => Promise.resolve(O.none),
      (userName) => {
        logger.info(`fetching user with userName: ${userName}`);
        return db.getUserByUserName(userName).then(O.some);
      }
    )
  );
};

const hasAuthParams: (currentUserName: Option<string>) => boolean = O.isSome;

Ahh, this is so much better. But why..., well let's see what kind of improvements we get to the list of issues from before.

Function inpurity:

The purity of this function is now dependent on what db.getUserByUserName does. We can assume that it queries the database and thus is impure. But we have eliminated the impurities that were caused by depending on values outside of the functions paramers.

Global shared state Makes program state unpredictable:

We are no longer using global shared state.

Mocking in tests becomes hard:

It suddenly became easy.

Concurrency issues:

No longer a problem.

Code comprehension:

Readibility increases significantly, when you can see the dependencies of the functions from it's type signature (parameters in this case).

Is this dependency injection?

Pretty much, it is a really basic application of dependency injection or inversion of control for backend development. Especially in a functional language or style we don't normally talk about dependency injection. But the idea is the same. In fact this kind of pattern in functional programming has been noticed a long time ago. We can abstract over passing configuration to our functions with the Reader data type.

const fetchUserReader: Reader<Config, Promise<Option<User>>> = pipe(
  R.ask<Config>(),
  R.map(({ currentUserName, db, logger }) =>
    pipe(
      currentUserName,
      O.fold(
        () => Promise.resolve(O.none),
        (userName) => {
          logger.info(`fetching user with userName: ${userName}`);
          return db.getUserByUserName(userName).then(O.some);
        }
      )
    )
  )
);

// This is a bit silly, I would probably leave this to the version without the reader
const hasAuthReader: Reader<Pick<Config, "currentUserName">, boolean> = pipe(
  R.ask<Pick<Config, "currentUserName">>(),
  R.map(({ currentUserName }) => O.isSome(currentUserName))
);

Without going to the detail you can think of the Reader<Config, string> as an abstraction for the following function (config: Config) => string. So it's just a function in disquise!

This is a bit silly in this context, since the example is so simple but in principle here's a couple of reasons you might consider the Reader data type.

Abstracting over function parameters can be useful to avoid the issue of passing the configuration object to every function as a parameter.
It can make code more readable. Goes kind of hand in hand with the previous point. (readibility is in the eye of the reader ;-))

Personally I propably wouldn't introduce the Reader monad in a client project, since it can scare some people off and doesn't bring enought benefits in the context of TypeScript to justify the costs (complexity, well again it's in the eye of the reader).

Footnotes:

The Option and Reader data types I used in this post are from fp-ts.
If you want to see how Reader is used in haskell and other similar languages here is the blog post that introduced the ReaderT pattern.

Implementing parser combinators pt. 2

Joona Piirainen — Wed, 09 Feb 2022 16:47:54 +0000

Welcome to part 2 of the series where we implement a simple parser combinator library from scratch in haskell. In the first episode we defined our Parser type and implemented all the necessary type-classes for it. You can find the source here. In addition to this we defined a couple of combinators, which allowed us to defined the following parser.

pKv :: Parser KV
pKv = KV <$> parseKv
  where
    parseKv = (,) <$> many alpha <* char ':' <* spaces <*> many alpha

This simple parser parses key-value pairs into an haskell data type. We are also able to run our parser.

runParser pKv "key: value" -- Right (KV ("key","value"))

This is already quite useful, but lets implement more combinators to make our little library feel a bit more polished. It would be nice if we could easily extend our previously defined pKv parser to parse lists of key value pairs. This will be trivial if we define a combinator called sepBy.

sepBy1 :: Parser a -> Parser b -> Parser [a]
sepBy1 p sep = (:) <$> p <*> many (sep *> p)

sepBy :: Parser a -> Parser b -> Parser [a]
sepBy parser separator = sepBy1 parser separator <|> pure []

Note that we defined sepBy by using a stricter version of itself. sepBy1 will fail if there is only one kv to parse, while sepBy parses it happily.

Now defining a parser that parses a list of kv's is trivial.

pKvs :: Parser [KV]
pKvs = pKv `sepBy` char ','

runParser pKvs "key: value,foo: bar" -- Right [KV ("key","value"),KV ("foo","bar")]

Nice. Now that I think of it, wouldn't it be nice to be able to parse numbers? I think so!

import Data.Maybe (fromMaybe)
import Data.Applicative (Alternative(..), optional) 
import Data.Functor (($>))

digit :: Parser Char
digit = satisfy "digit" Char.isDigit

decimal :: (Integral a, Read a) => Parser a
decimal = read <$> many1 digit

signedDecimal :: Parser Int
signedDecimal = fromMaybe id <$> optional (char '-' $> negate) <*> decimal

Now we can parse numbers, Hooray! Here's a couple of examples.

runParser (decimal @Int) "123" -- Right (123)
runParser (decimal @Int) "-123" -- Left "Expecting digit at position 0"
runParser signedDecimal "-123" -- Right (-123)

Parsing whitespace is also a common task, especially when you are writing a lexer. Let's define some useful combinators to make lexing more convenient.

spaces :: Parser ()
spaces = void $ many (satisfy "whitespace" Char.isSpace)

newline :: Parser ()
newline = char '\n' <|> (char '\r' *> char '\n')

horizontalSpaces :: Parser ()
horizontalSpaces = void . many $
  satisfy "horizontal whitespace" $ \c ->
    Char.isSpace c && c /= '\n' && c /= '\r'

When we previously parsed key value pairs, they were separated by commas. You might also want to parse key value pairs separated by newlines.

key: value
foo: bar

Let's write a parser for this.

pKvsNewLine :: Parser [KV]
pKvsNewLine = pKv `sepBy` newline

runParser pKvsNewLine "key: value\nfoo: bar" -- Right [KV ("key","value"),KV ("foo","bar")]

Or we could want to parse kv's which are separated by commas but have some random spaces in between them. Eg. "key: value , foo: bar". We can use horizontalSpaces for this!

pKvsHorizontal :: Parser [KV]
pKvsHorizontal = pKv `sepBy` s
  where s = horizontalSpaces *> char ',' <* horizontalSpaces

runParser pKvsHorizontal "key: value       ,        foo: bar" -- Right [KV ("key","value"),KV ("foo","bar")]

At this point we have quite a powerful set of tools in our hands. We still haven't seen any interesting use-cases for this machinery. In the next part we will define a parser for a simple programming language.

Thank you for reading, hope you enjoyed. Have a nice day!

Joona

Part 1
Other blog posts by me

Implementing parser combinators pt. 1

Joona Piirainen — Mon, 10 Jan 2022 10:19:15 +0000

One of the many strengths of haskell is the ability to easily embed other small languages (sometimes called EDSL, short for embedded domain specific language) inside it. One famous example of this is the family of libraries known as parser combinators. They aim to solve the task of parsing structured text into well-typed data-structures, and succeed in it quite beautifully. In this short series of blog posts I will show you how to implement a simple and usable parser combinator library. You can find the source code for the library we will be developing here. For real world use-cases you should propably just use megaparsec.

MicroParser

So now let's build own own toy parser combinator library! We will call it MicroParser.

{-# LANGUAGE DeriveFunctor #-}
module MicroParser where

import Control.Applicative (Alternative (..))
import Control.Monad (void)
import qualified Data.Char as Char
import Data.List (intercalate)

Let's start by thinking what the type of a parser should be? Structurally a parser is a function which takes an input stream of characters and yields a parse tree by applying the parsing logic over the input stream of characters to build up a composite data structure.

data ParseResult
    = ParseSuccess !a !Int String
    | ParseFailure [(Int, String)]
    deriving (Functor, Show)

newtype Parser a 
    = Parser {unParser 
              :: Int
              -- ^ offset
              -> String
              -- ^ input stream of characters
              -> ParseResult a
              }

Our parser is polymorphic over the thing our parser should produce when successful. Internally our parser function takes an Int as it's first argument, which represents the position of the character we are currently parsing. This is useful for reporting errors. Other than that the type is relatively straight forward. Let's define a function for running a parser.

runParser :: Parser a -> String -> Either String a
runParser (Parser p) ts = case p 0 ts of
  ParseSuccess x _ _ -> Right x
  ParseError es ->
    Left $
      "Expecting "
        <> intercalate
          " OR "
          [ e <> " at position " <> show i
            | (i, e) <- es
          ]

Running a parser yields either a parse result when successful and an error message in the case of an error, which we represent here as a (somewhat) formatted string. In proper parser combinator libraries error handling is handled in more elegant and structured ways.

Now we have defined the basic structure of our library, but it is not very usable at this point. We have no convenient way of constructing parsers nor do we have any way of combining them. So clearly we need to do some more work. The power of parser combinators mostly come from the typeclass instances we define for our Parser type. Especially Applicative and Alternative in our case. Some parser combinator libraries encourage the usage of the syntactic sugar haskell provides for monads. We are not going to define a monad instance for our parser since we can do plenty without it.

To define Applicative and Alternative instances we need to first define Functor for out Parser type. Here is the Functor instance definition for our Parser type.

instance Functor Parser where
    fmap f (Parser p) = Parser (\i ts -> fmap f (p i ts))

Now we can move on to the more interesting instances. Let's start with Applicative.

instance Applicative Parser where
    pure x = Parser (ParseSuccess x)
    Parser a <*> Parser b =
        Parser
            ( \i ts ->
                case f i ts of
                  ParseError es -> ParseError es
                  ParseSuccess x i' ts' -> case g i' ts' of
                    ParseError es' -> ParseError es'
                    ParseSuccess x' i'' ts'' -> ParseSuccess (x x') i'' ts''
            )

This might be a bit intimidating if you are unfamiliar with Applicative. I'll not go through explaining Applicatives in detail here, since it's out of the scope of this blog post, but I highly suggest learning what they are and to start building an intuition on when you should use them. Here is a good starting point.

Alternatives

Next we will define Alternative. Alternative is not as well known as typeclasses such as Functor, Applicative and Monad but are super useful for our use-case, so I think it's worth looking at them in a bit more detail.
The Alternative typeclass has four members including empty, some, many and most importantly for us <|>. Let's explore what <|> does. The Maybe data type is well known so I will use it for demostration purposes since most people know what it represents. For me the mental model for <|> is the following. "Try executing the left hand side function and if successful, return the result, otherwise return the result of calling the right hand side function". (This mental model happens to work for Maybe, but is not always correct since the operator can have different effects on other data types.)

ghci> Just 4 <|> Just 5
Just 4
ghci> Just 4 <|> Nothing
Just 4
ghci> Nothing <|> Just 4
Just 4
ghci> Nothing <|> Nothing
Nothing

But we are implementing parsers... how can we use this? Well we can express choice with it. Particulally we can think of it as saying "try parse this, then try parse this, then try parse this, and so on". This might sound a bit abstract at this point. But will become clear when we are finished!

instance Alternative Parser where
  empty = Parser (\_ _ -> ParseError [])
  Parser f <|> Parser g =
    Parser
      ( \i ts ->
          case f i ts of
            success@ParseSuccess {} -> success
            ParseError errs0 -> case g i ts of
              success@ParseSuccess {} -> success
              ParseError errs1 -> ParseError (errs0 <> errs1)
      )

This instance definition actually follows the mental model quite clearly. "Run the first parser, if successful, return the results, otherwise run the second parser".

We are getting closer. Almost all the hard work is now done and we can move on to the fun part.

Combinators

To wrap up the first part of this series of posts, we will define a fundamental combinator found in almost all of the parser combinator libraries, satisfy, and show a couple of use-cases for it. We will write satisfy in terms of a more general function called satisfyMaybe, which takes a description (used for error messages), a function from Char to a Maybe value indicating weather the character satisfies some condition or not.

satisfyMaybe :: String -> (Char -> Maybe a) -> Parser a
satisfyMaybe descr p =
  Parser
    ( \i ts -> case ts of
        (t : ts') | Just x <- p t -> ParseSuccess x (i + 1) ts'
        _ -> ParseError [(i, descr)]
    )

satisfy :: String -> (Char -> Bool) -> Parser Char
satisfy descr p = satisfyMaybe descr (\t -> if p t then Just t else Nothing)

Once we have satisfy we can define various combinators based on it. We will start with one that parses any character, one that parses a specific character, one for parsing whitespace and finally one that parses a specific sequence of characters.

anyChar :: Parser Char
anyChar = satisfy "any character" (const True)

char :: Char -> Parser ()
char c = void $ satisfy (show c) (== c)

spaces :: Parser ()
spaces = void $ many (satisfy "whitespace" Char.isSpace)

string :: String -> Parser ()
string [] = pure ()
string (x : xs) = char x *> string xs

Here's an example of how one might use these. Suppose we want to parse a key value pair into a KV data type.

-- | example kaye value pair
text :: String
text = "key: value"

-- | Data type we would like parse the text into
newtype KV = KV (String, String) deriving (Show)

We can do this via the following parser. Here we leverage some of the combinators we defined previously.

pKv :: Parser KV
pKv = KV <$> parseKv
  where
    parseKv = (,) <$> many alpha <* char ':' <* spaces <*> many alpha

Admittedly this example is not the best one and doesn't show the full power of parser combinators. We need some additional combinators to gain more power to see what they are really capable of. But that is a challenge we will tackle in part 2 of this series of posts.

Thank you for reading, hope you enjoyed. Have a nice day, and until next time!

My other posts can be found here.

Joona

Thoughts on Clojure λ

Joona Piirainen — Fri, 07 Jan 2022 14:15:53 +0000

2021 was the first year I participated in AdventOfCode, which is the worlds largest programming contest. I solved the 2021 puzzles in Haskell and Python. Doing AOC puzzles became a habit I enjoyed, so I couldn't stop on the 25th of december, and started solving the year 2015. I do AOC puzzles to improve my general problem solving skills, but they are also a convenient place to learn new programming languages! So obviously (if you read the title) I chose Clojure for the year 2015. In this post I'd like to summarize my thoughts on the language after solving all 25 problems using it.

The Good

Surprisingly easy to pick up

This was the first time writing in any of the lisp-family programming languages. Surprisingly, the learning curve wasn't too bad. After a couple of days I felt quite comfortable writing clojure code. Being able to pick up a language quickly is a positive thing for sure!

Standard library

Clojure standard library was great and felt polished. Especially enjoyed the data-structures provided.

Threading macros

I'm talking about these guys.

Thread-last. This was the variant I used 90% of the time. Don't know if this is idiomatic, but I guess this is the way I think about the data flowing in programs.

(->> [1 2 3] (map inc) (reduce +)) ;; => 8

Thread-first. Didn't use this variant too much, but useful for chaining functions that take data as the first argument. (Personally don't know why everything is not data last??)

(map #(-> % (str/split #": ") (nth 1) read-string) "foo: 123") ;; => 123

REPL

Being able to develop API's using the REPL was nice.

Docs

clojuredocs were nice and had comprehensive and easy to follow examples.

The bad

Error messages

When you got an exception the top most call site would be reported, not where the actual exception occurred. How is that a thing?

Getting my development environment setup

This was a pain. I tried using vscode with calva, but gave up pretty soon after starting. Ended up using emacs with cider, which was pretty nice, but had a huge learning curve for me since I'm not an emacs user. (Maybe I am after this...)

Dynamic nature of lisps

I'm a believer of strong static types, and using clojure made me have even stronger opinions on the matter. Dynamic typing combined with the error messages was honestly terrible at times. This is probably the biggest reason I will likely not return to writing in clojure (at least if I don't have to).

Summary

Overall Clojure was an OK language despite the gripes I have with it. Initially I was steered to trying it since it seems to be kind of popular here in Finland and I wanted to see if I would like to write it professionally at some point (I don't.. At least for now). I honestly have no idea if the code I wrote was idiomatic Clojure code or not (probably not). I will link the repo below and please tell me if it was the way I was using the language that made me not enjoy it more than I did.

Code on Github.
My other blog posts.

Typesafe express routes

Joona Piirainen — Sun, 10 Oct 2021 10:56:09 +0000

Recently I've spent a lot of time writing Haskell. In Haskell-land there's a lot of bleeding-edge research stuff, which is cool, but most likely not very applicable for my day-to-day work. If there's one thing that all haskellers love, it must be type-safety. That's what this post is about, bringing some type-safety to our node.js apps, more specifically express or koa apps. I'll try to point to some flaws I see in the typical way of writing express/koa apps with typescript and propose a "better" way.

Motivating example

Let's start by defining routes we would like to implement. Suppose you are writing some CRUD operations for some "users" resource. We will use the following endpoint schema as an example.

GET /users     => Ok<[User]>
GET /users/:id => Ok<User> | NotFound
POST /users    => Ok | BadRequest
PUT /users/:id => Ok<User> | BadRequest | NotFound

The example endpoints will be using this interface for querying a "database". Implementation details of this interface are not relevant for this post. (There is a link at the end to a gist containing all the code in these examples.)

interface UsersRepo {
  all: () => Promise<User[]>
  findById: (id: number) => Promise<Option<User>>
  create: (name: string) => Promise<Id>
  update: (id: Id, update: { name: string }) => Promise<Option<User>>
}

Let's write some express endpoints

Let's start with the "GET all users" and "GET user by id" endpoints.

app.get('/users', async (_req, res) => {
  const users = await usersRepo.all()
  return res.json(users).status(200)
})

app.get('/users/:id', async (req, res) => {
  const user = await usersRepo.findById(+req.params.id)
  if (isNone(user)) return res.status(404)
  return res.json(user.value).status(200)
})

The "GET all users" endpoint is not so bad. There's no risk for anything blowing up because of some type-error. The second endpoint is already starting to show some problems. By default request parameters captured by express is of type "string", which is bad for us since our database interface requires the user's id as a number. Nothing is validating that req.params.id is a number, so the conversion to number might throw. Also, nothing is checking that the id is even present in "req.params".

Next, we'll look at our POST and PUT endpoints. These start to show the issues I'm trying to highlight.

app.post('/users', async (req, res) => {
  const { name } = req.body // req bodys type is any. This line also throws if name is not present in req.body
  const id = await usersRepo.create(name)

  const user = await usersRepo.findById(id)
  if (isNone(user)) return res.status(404)
  return res.json(user.value).status(200)
})

app.put('/users/:id', async (req, res) => {
  const { id } = req.params // req.params is of type any. Also throws in case id is missing in req.params.
  const user = await usersRepo.update(+id, req.body) // same problem again with req.body
  if (isNone(user)) return res.status(404)
  return res.status(200).json(user.value)
})

I documented some of the problems with code comments. There are also some more nuanced issues I see here. Nothing is checking what status codes we are returning or validating checking that the JSON we are sending is of type User. We could return an elephant instead of a user and the type-system wouldn't notice a thing. These are not very big problems in this contrived example but I hope you get the point.

Let's consider the following change in our UsersRepo interface.

Interface UsersRepo {
  all: () => Promise<User[]>
  ...
}
// changes to  ⬇️

Interface UsersRepo {
  all: () => Promise<Option<User[]>>
  ...
}

So now for whatever reason, our all users action returns Option. What kind of type errors do we get? Is our code going to compile?

Unfortunately yes. Typescript says everything is fine. Hopefully, our test coverage catches these kinds of mistakes, but in my opinion, this should never get through the compilation step.

How can we improve from this?

Luckily we are not doomed. There are better ways to do this. I will be using this awesome open-source library called typera. You can use it on top of either express or koa. I'm going to use it with express so I'll add "typera-express" to my package.json and add the following imports.

import { Route, Response, Parser, route, router } from 'typera-express'

Here is the "GET all users" endpoint rewritten with typera.

const users: Route<Response.Ok<User[]>> = route
  .get('/users')
  .handler(async () => Response.ok(await usersRepo.all()))

Compare it to the previous implementation. Do you see any improvements?

app.get('/users', async (_req, res) => {
  const users = await usersRepo.all()
  return res.json(users).status(200)
})

In this simple endpoint, the benefits are not huge, but there are some improvements. First of all, you can see what the endpoint is capable of returning, in this case, Response.Ok. Also, note the usage of Response.ok() instead of res.json().status(200). This makes our job easier since we don't need to think about the status codes we're returning, thus reducing the chance of us writing bugs.

Here's the "update user" endpoint rewritten with typera.

const updateUser: Route<
  Response.Ok<User> | Response.NotFound | Response.BadRequest<string>
> = route
  .put('/users/:id(int)')
  .use(Parser.body(t.type({ name: t.string })))
  .handler(async ({ body, routeParams: { id } }) => {
    const updatedM = await usersRepo.update(id, body)
    if (O.isNone(updatedM)) return Response.notFound()
    return Response.ok(updatedM.value)
  })

There's a lot going on, so let's break it down.

Route | Response.NotFound | Response.BadRequest>. We list the possible return values of our endpoint.
.put('/users/:id(int)'). This line is interesting. Typera calls these param conversions. Typera will validate that the "id" in query parameter is of type int and return BadRequest in the case this requirement is not met.
.use(Parser.body(t.type({ name: t.string }))). This line takes care of request body validation. You can use any valid io-ts validation schemas with typera. If you are unfamiliar with io-ts, I highly recommend checking it out!
Now in the handler function we get the validated and correctly typed request body and query parameters.

That's a huge improvement compared to the initial version. After embracing the power type-safety gives you, just looking at the initial version is giving me headaches. I know this toy example is not the perfect way to motivate you to introduce this complexity to your codebase since you start seeing the benefits when your application gets bigger and you need to start making changes. The point I'm trying to make is that I think static types and type-safety make your code better, cleaner, and most importantly more maintainable.

Hope you learned something from this post. Cheers!

Links:

typera: https://github.com/akheron/typera
example source of the typera version: https://gist.github.com/japiirainen/5061fd58d5a7d52f535fb053f99d3bc9
my github: https://github.com/japiirainen
my website: https://japiirainen.com

Immutable data structures in TypeScript

Joona Piirainen — Mon, 01 Feb 2021 17:19:02 +0000

Why would you want immutable data structures?

Immutable data structures are essential when you try to code in a functional way, and JavaScript by itself doesn't support these. Luckily we can leverage the type system provided by TypeScript to enforce these immutability rules on our frequently used data structures like arrays and objects.
I only recently found out about this feature and thought that other people might have also missed out so making this short blog post to hopefully provide useful information for at least a couple of you guys!

Arrays

Regular way to initialize an array filled with some integers.

const xs = [1, 2, 3, 4, 5]

The problem with this is that even though we are using const to prevent reassignments we are allowed to mutate the array as we please.

xs[1] = 100
console.log(xs) -> [1, 100, 3, 4, 5]

We can luckily fix this by just giving xs the type ReadOnlyArray.

const xs: ReadOnlyArray<number> = [1, 2, 3, 4, 5]

Now we are not allowed to mutate the array!

xs[1] = 100
console.log(xs) -> error TS2542: Index signature in type 'readonly number[]' only permits reading.

This is quite awesome. Enforcing immutable data structures makes our code both easier to understand and to maintain. If you are freaked out by this and thinking that what can you even do with these data structures that cannot be changed, stop worrying!. We can still use all the functional techniques that won't modify the values in place, but return new values instead.

examples

const biggerXs = xs.map(x => x * 100)
const largestInXs = xs.reduce((acc, x) => x > acc ? x : acc)
const evenOnly = xs.filter(x => x % == 0)

Objects

We can do similar things with objects.

Regular way to initialize a user object.

const user = {
    firstname: 'foo',
    lastname: 'bar',
    age: 69,
}

I didn't define a type or an interface because in these kinds of situations the compiler can infer the types for free. If you want to make this immutable you actually have to define an interface for the type.

Immutable way to initialize a user object._

interface Iuser {
    readonly firstname: string
    readonly lastname: string
    readonly age: number
}
const user: Iuser = {
    firstname: 'foo',
    lastname: 'bar',
    age: 69,
}

Not if we try to modify a field on our user we get a similar compiler error as before with arrays.

user.firstname = 'bar' -> error TS2540: Cannot assign to 'email' because it is a read-only property.

Now if we want to update the user we need some functional techniques again...

const incUserAge = (user: Iuser): Iuser => ({ ...user, age: user.age + 1 })

const birthdayBoy = incUserAge(user) -> { firstname: 'foo', lastname: 'var', age: 70 }

That's all I wanted to share in this blog post. Hope you found it useful. I will post more stuff related to FP in the future so consider giving me a follow if that sounds interesting ;-).
You can find other blog posts by me on my website.

Intro to RecoilJS. Build a small app with Recoil!

Joona Piirainen — Sat, 04 Jul 2020 11:10:32 +0000

what is recoilJS?

RecoilJS is yet another state management library for React. It is maintained and open-sourced by Facebook. But why would we need another state management library since we already have so many? Well, I’m not quite qualified enough to answer this question so you should read the recoilJS docs. But at least in my eyes recoilJS makes more complex state management simpler and removes a lot of the boilerplate that would otherwise be involved. RecoilJS syntax is Reactish as they said in the docs and it almost feels like it’s a part of the React API.

Building a simple expense tracker

This app is highly based on Brad Traversy’s expense tracker from his vanilla javascript projects. I just thought this would be an excellent little app that needs some state management to work. So I will be showing you how to create this fun little app using React with recoilJS.

This app will consist of components that will be able to:

Display transaction items
Show balance, expense and income totals
Add new transaction that reflects the total amount
Delete items
Persist to local storage

This tutorial assumes that you have at least some experience with React and Hooks in advance.

You can find the code in this Github Repo.

Here’s a picture of my file structure to make things more clear!

So let’s start writing it!

first, we jump into the root directory and wrap the App.js component with RecoilRoot. In this application the App.js component will contain all other components.

index.js

import React from "react"
import ReactDOM from "react-dom"
import App from "./App"
import { RecoilRoot } from "recoil"

ReactDOM.render(
  <React.StrictMode>
    <RecoilRoot>
      <App />
    </RecoilRoot>
  </React.StrictMode>,
  document.getElementById("root")
)

RecoilRoot is the actual component that will provide our state across our whole application. You can think of it similarly to let’s say a context provider while using React’s useContext hook or a store provider when using redux.

Atoms

atoms.js

import { atom } from "recoil"

export const transactionListState = atom({
  key: "transactionListState",
  default: [
    {
      id: 1,
      amount: 10,
      text: "Found a 10 dollar bill!",
    },
    {
      id: 2,
      amount: -110,
      text: "New keyboard",
    },
    {
      id: 3,
      amount: 300,
      text: "Sold my old Playstation!",
    },
  ],
})

In recoilJS, atoms are units of state. They are updateable and subscribable, which means that when an atom is updated, each subscribed component is re-rendered with the new value.
We need to give each atom a unique key and set some default value, just like with the useState hook. My atom will eventually have an empty array([]) as its default value. I just gave some initial data, so it’s easier to understand what’s going on :-). If this is not making any sense right now, I promise it will soon!

Lets jump into the Transaction.js component that will contain a single transaction and later we will display many of these in the TransactionList.js component.

import React from "react"

export const Transaction = ({ transaction }) => {
  return (
    <li className={transaction.amount}>
      {transaction.text}
      <span>{transaction.amount}</span>
      <button className="delete-btn">x</button>
    </li>
  )
}

Right now we don’t have much there just a template ready to take in some data. Next, we will display the data I already have inside my atom from TransactionList.js!

import React from "react"
import { Transaction } from "./Transaction"
import { transactionListState } from "../recoil/atoms"
import { useRecoilValue } from "recoil"

export const TransactionList = () => {
  const transactionList = useRecoilValue(transactionListState)

  return (
    <>
      <h3>Transaction History</h3>
      <ul className="list">
        {transactionList.map(transaction => (
          <Transaction key={transaction.id} transaction={transaction} />
        ))}
      </ul>
    </>
  )
}

So if you are familiar with react this will probably look quite similar to what you have previously seen. Here we use useRecoilValue instead of useRecoilState because we only read the current state of our transactionListState atom.
Then we just map our array of transactions into the Transaction.js component and send the data down with props. Let’s take a look at the NewTransaction.js component.

import React, { useState } from "react"
import { transactionListState } from "../recoil/atoms"
import { useSetRecoilState } from "recoil"
import { v4 as uuidv4 } from "uuid"

export const NewTransaction = () => {
  const [textValue, setTextValue] = useState("")
  const [amount, setAmount] = useState(0)
  const setTransactionList = useSetRecoilState(transactionListState)

  const NewTransaction = e => {
    e.preventDefault()
    setTransactionList(oldTransactionList => [
      ...oldTransactionList,
      {
        id: uuidv4(),
        amount: +amount,
        text: textValue,
      },
    ])
    setTextValue("")
    setAmount(0)
  }

  const handleTextValue = e => {
    setTextValue(e.target.value)
  }
  const handleAmount = e => {
    setAmount(e.target.value)
  }

  return (
    <>
      <h3>Add new transaction</h3>
      <form>
        <div>
          <label htmlFor="text">Description</label>
          <input value={textValue} onChange={handleTextValue} />
        </div>
        <div>
          <label htmlFor="amount">
            Amount <br />
          </label>
          <input value={amount} onChange={handleAmount} />
        </div>
        <button onClick={NewTransaction}>Add transaction</button>
      </form>
    </>
  )
}

So here we need to be able to add a new transaction to our atom that contains the current state of our transactions list. Therefore we use useSetRecoilState which allows us to do just that! Our NewTransaction function sets the state to contain all the transactions that were already there and adds a new item into the list.

And if you were wondering what’s going on with id: uuidv4(), it’s just a library that generates some random id’s for us!

Selectors

The second core concept of Recoil is Selectors. As they state in the docs, a selector represents a piece of derived state. You can think of derived state as the output of passing state to a pure function that modifies the given state in some way.
So we need to be able to calculate the total balance based on the current state of our transactionList. This is a perfect place to use a selector! We will declare a new selector in Selectors.js.

import { transactionListState } from "./atoms"
import { selector } from "recoil"

export const balanceState = selector({
  key: "balanceState",
  get: ({ get }) => {
    const transactionList = get(transactionListState)
    const amounts = transactionList.map(transaction => transaction.amount)
    const balance = amounts.reduce((acc, num) => (acc += num), 0).toFixed(2)

    return balance
  },
})

Selectors also take in a unique key, but they don’t have a default value, but instead, they have getand set properties. We will only need the get property so we’ll focus on that. With the get property, we can get the value of some atom and do stuff with it. In our case, we use our transactionListState atom, and we want to add together all the amount properties of the transactions.
After the calculation, we just return the result, and we can use it in our Balance.js component!

import React from "react"
import { useRecoilValue } from "recoil"
import { balanceState } from "../recoil/selectors"

export const Balance = () => {
  const balance = useRecoilValue(balanceState)

  return (
    <>
      <h4>Your Balance</h4>
      <h1>{balance}</h1>
    </>
  )
}

Quite simple right? 😺

Now let’s make one more selector that will allow us to display the total amounts of incomes and expenses.

export const expenseStatsState = selector({
  key: "expenseStatsState",
  get: ({ get }) => {
    const transactionList = get(transactionListState)
    const amounts = transactionList.map(transaction => transaction.amount)
    const income = amounts
      .filter(num => num >= 0)
      .reduce((acc, num) => (acc += num), 0)
      .toFixed(2)

    const expense =
      amounts.filter(num => num < 0).reduce((acc, num) => (acc += num), 0) *
      -(1).toFixed(2)

    return {
      income,
      expense,
    }
  },
})

Lets use it in ExpenseStatus.js. We access the value a bit differently now since we returned an object that contains two values, so we use deconstructing.

import React from "react"
import { useRecoilValue } from "recoil"
import { expenseStatsState } from "../recoil/selectors"

export const ExpenseStatus = () => {
  const { income, expense } = useRecoilValue(expenseStatsState)

  return (
    <div className="expense-status-container">
      <div>
        <h4> Income </h4> <p className="money plus">{income}</p>
      </div>
      <div>
        <h4> Expense </h4> <p className="money minus">-{expense}</p>
      </div>
    </div>
  )
}

Removing transactions

We are still missing the ability to remove stuff from our list of transactions, so let’s make that possible! We already have a delete button inside of our Transaction.js component so we just need to add some functionality.

import React from "react"
import { useRecoilState } from "recoil"
import { transactionListState } from "../recoil/atoms"
import { removeItemAtIndex } from "../utils"

export const Transaction = ({ transaction }) => {
  const [transactionList, setTransactionList] = useRecoilState(
    transactionListState
  )
  const index = transactionList.findIndex(listItem => listItem === transaction)

  const removeTransaction = () => {
    const newList = removeItemAtIndex(transactionList, index)
    setTransactionList(newList)
  }

  const sign = transaction.amount < 0 ? "-" : "+"

  return (
    <li className={transaction.amount < 0 ? "minus" : "plus"}>
      {transaction.text}
      <span>
        {sign}${Math.abs(transaction.amount)}
      </span>
      <button className="delete-btn" onClick={removeTransaction}>
        x
      </button>
    </li>
  )
}

//  helper function for removing a transaction
const removeItemAtIndex = (arr, index) => {
  return [...arr.slice(0, index), ...arr.slice(index + 1)]
}

Now we finally use useRecoilState! As you can see it’s just like using the useState hook in vanilla React. The reason I need to do Math.abs() which gives me the absolute value of the number we pass into it is that it makes all the negative numbers positive, so the logic for putting the sign ahead of the number doesn’t get messed up.

Finally!

Let’s implement local storage, so all our transactions don’t disappear if we reload our page!
We just need to update two of our components to get this working.

Firstly @ NewTransaction.js we just add this code snippet after our NewTransaction function to set all transactions that we create to localStorage. We also need to change from using useSetRecoilState to useRecoilState since we need to pass our transactionList to localStorage.

useEffect(() => {
  localStorage.setItem("TRANSACTION_LIST", JSON.stringify(transactionList))
}, [transactionList])

And @TransactionList.js we switch from using useRecoilValue to*useRecoilState* since if we find some transactions in local localStorage we need to set the list state to match that.

import React, { useEffect } from "react"
import { Transaction } from "./Transaction"
import { transactionListState } from "../recoil/atoms"
import { useRecoilState } from "recoil"

export const TransactionList = () => {
  const [transactionList, setTransactionList] = useRecoilState(
    transactionListState
  )
  useEffect(() => {
    setTransactionList(JSON.parse(localStorage.getItem("TRANSACTION_LIST")))
  }, [setTransactionList])

  return (
    <>
      <h3>Transaction History</h3>
      <ul className="list">
        {transactionList !== null &&
          transactionList.map(transaction => (
            <Transaction key={transaction.id} transaction={transaction} />
          ))}
      </ul>
    </>
  )
}

So that’s it! I hope you found this article useful in some way.

👋🏼👋🏼