DEV Community: Jason

WebAuthN in Remix - FaceID, YubiKey, and more!

Jason — Thu, 07 Dec 2023 16:06:49 +0000

This article covers how to add "passwordless" authentication to any Remix application using WebAuthN. This allows users to authenticate using their iPhones FaceID, TouchID, a physical security key like a YubiKey, or a virtual Passkey that can be stored in password managers like LastPass/Bitwarden/OnePassword etc..

“Passkeys are like passwords but better. They’re better because they aren’t created insecurely by humans and because they use public key cryptography to create much more secure experiences.”

- https://passkey.org

Why integrate with WebAuthN? (ELI5)

WebAuthN is a more secure and usually a better UX for users to authenticate with your application. Instead of typing a password, or opening a password manager and finding your login credentials, one can just use their phone's native bio authentication mechanisms like FaceID or fingerprints to authenticate.

This involves creating a pair of private and public keys and storing the private keys on a local device, and sharing the public keys with a server's database. This process is facilitated by WebAuthN standards.

“Although there are many ways to do MFA, security keys are a highly secure and convenient option. Login codes sent via text message can be intercepted, and authentication apps require that your phone be charged and available.”

- https://www.yubico.com

Even if the database's data is compromised and data is leaked, it will not matter because the public key does not have any important information - it is only useful when paired with the private key.

Adding this feature to your application allows extra security by enforcing it after a normal login for an MFA flow, or just to replace the password altogether. It can also be considered a faster MFA implementation because it does not require waiting for a text message or email with a code to copy/paste, or an Authenticator app to copy/paste 6-digit codes from.

How to integrate WebAuthN into Remix

The process involves two steps. First step is to have users register some credentials, the second step is to use the credentials when the user tries to login in the future and verify their identity.

This process can be achieved completely "natively" by using the Browsers navigator.credentials API for creating a getting keys on the client side, but it can be more tedious overall since it is more low level.

So this article will use the great library SimpleWebAuthN from Matthew Miller, which provides packages for the server side, client side, and typescript types, that make everything easier.

Registering Credentials

For both registration and authentication of credentials, the flow is similar. For registration it goes like this:

The client indicates to the server that it wants to register some new credentials.
The server generates some options that it will pass back to the client, which includes a secret challenge. This is done in the library with webauthn.generateRegistrationOptions(...). The secret challenge is stored in a readonly http session cookie.
The client takes the options and passes it to the WebAuthN facilitator, such as SimpleWebAuthN library to do webauthn.startRegistration(options) - the client will be prompted by the browser or native OS to choose a format, such as FaceID or passkey.
The client then takes the result of the registration and passes it back to the server.
The server validates and verifies the results with something like webauthn.verifyRegistrationResponse(results) which includes the secret challenge from the session.
If the verification passes, the publicKey is stored in the database, along with the corresponding credentialID, the transports and a counter. The transports just indicate the type of device that was used, such as a USB key or other means, and the counter is used to ensure the same device is not used too many times. This data will be fetched and used when the user tries to login later.

Side note: When generating the options on the server - the server can include already existing keys for that user in the options response to prevent the client from trying to register the same credential twice.

Overall, there are a few back-and-forth requests between server and client, and in Remix this can be handled in a few different ways, either using native Forms or by using Remix's useFetcher hooks, or just with normal http ajax requests like Fetch, Axios or the O.G XMLHTTPRequest.

Session cookies are stored using Remix's createCookieSessionStorage().

Authenticating

After the credentials are created and stored on the user's device and the public key is stored in the app's database, we can now use them to authenticate the user.

The flow is as follows (for passwordless):

The user indicates to the server that they would like to login.
The server generates some options that it will pass back to the client, which includes a secret challenge. This is done in the library with webauthn.generateAuthenticationOptions(...). The secret challenge is stored in a readonly http session cookie.
The client takes the options and passes them to webauthn.startAuthentication(options) - the client will be prompted by the browser or native OS to choose a format, such as FaceID or passkey.
The client then takes the result of the registration and passes it back to the server.
The server validates and verifies the results with webauthn.verifyAuthenticationResponse(results) which includes the secret challenge from the session.
If the verification passes, the user is considered valid and another session cookie is set, such as isLoggedIn and is set to true, with an expiry date for however long you want the user to be authenticated without having to re-authenticate. The server can redirect the user to an authenticated page with the new session cookie so they can use the app freely, and authenticated.

Recovery

Overall WebAuthN is a great solution for stellar UX and strong security in applications - but a drawback can be if the user loses their security device, or loses their phone which holds their private keys. This would mean they lose access to any application that requires their private key for authentication on the client side.

That's why it is important to also provide a recovery mechanism for lost devices. Most applications provide a series of "codes" that the user should store somewhere else, in case they lose access to their primary device, they can add a new device using the recovery codes.

Conclusion

That's it! It is pretty simple to integrate WebAuthN into Remix applications, and it provides great UX and great security for users.

For further information about WebAuthN, check out their official site webauthn.io!

Follow me on twitter (@Rametta) to hear about new articles.

Godot Data Validation with Zodot

Jason — Tue, 17 Oct 2023 15:07:23 +0000

Zodot is a new data validation library for Godot, with an API that was inspired by the popular Typescript/Javascript npm package Zod.

Data validation is an important concept in many programming environments, including Godot. It is the process of taking unknown data and confirming that it matches the shape that is expected. If the data does not match the
expected shape, then gracefully handle the error.

Features

Some of Zodot's convenient features include:

Typed dictionaries in GDScript
Typed Unions
Support for nullables
Automatic data coercing with str_to_var()

More details on these features below.

When to use Zodot

Oftentimes in game development, or any development - developers will store or retrieve data externally from their codebase, either from a database, an API rest endpoint, a file, or just an external package. Such data can be things like a player's inventory system, their statistics, lobby information, friends lists, or more.

No matter how you retrieve some external data, the important step is to validate that the data you received matches the shape that you are expecting, otherwise you may start accessing the data when assuming its shape, but results in a runtime crash when the data has changed unexpectedly.

How to use Zodot

Using Zodot is super easy. The first thing to do is define a schema, and then use the schema to parse the data that you want to validate.

Example of defining a player schema with 3 fields:

var PlayerSchema = Z.schema({
  "user_id": Z.string(),
  "avatar_color": Z.color(),
  "position": Z.vector3()
})

This schema defined an object with 3 typed fields. Now we can take some data and pass it to the schema to be validated against:

func parse_player(data: Variant):
  var result = PlayerSchema.parse(data)

  if not result.ok():
    print("The data does not match the expected shape")
    print(result.error)
    return

  # Do things with the valid data now
  print(result.data)

In the above example, we see the data comes in as a Variant type, which just means it could be anything, then we pass that to our schema. If our result from the parse is not ok, then we have access to a detailed error message as result.error. If it does match the schema, then we have access to the typed data in result.data.

Data Coercing

One of the best features of Zodot is its ability to corece data before validating. This is popular when complex data is stored as strings and then needs to be deserialized back into its real type after retrieval. Let's look at an example:

var schema = Z.schema({
  "color": Z.color().coerce(),
  "position": Z.vector2().coerce()
})

We use the .coerce() extension for each field we want to deserialize because we are expecting to receive that field as a string that was previously serialized using Godot's var_to_str method.

Now if we have serialized data such as:

# notice the values are wrapped in strings
var data = {
  "color": "Color(1,2,3,.5)",
  "position": "Vector3(4,2,5)"
}

We can parse it and receive the actual types after successful validation:

var result = schema.parse(data)
print(result.data.color) # Color(1,2,3,.5) - real type, not wrapped in strings

Typed Dictionaries

Zodot provides some powerful features that are not even available in GDScript, such as typed dictionaries. Take a look at a dictionary example:

var schema = Z.schema({
  "other_field": Z.float(),
  "my_dict": Z.dictionary(Z.color())
})

Since GDScript can't define the type for the dictionary values, we can use Zodot's dictionary validator to ensure that all the values in the dictionary are of a certain type - like this example, all values in the dictionary must be a Color type.

Typed Unions

Another powerful validator from Zodot is called z.union() which is another feature that GDScript does not provide. This validator allows fields to be more than one type.

Z.schema({
  "user_id": Z.union([Z.string(), Z.integer()])
})

In this example, the user_id is defined to accept a string or even an integer as a valid type! This is similar to other languages like Typescript which would be defined as: type UserId = string | number

Nullables

One last feature of Zodot is its ability to allow any field to be null just by adding .nullable() to the end of the field validator.

var nullable_color_field = z.color().nullable()

This makes it much more clear than the basic GDScript type definitions since GDScript has no real way of defining that relationship.

Try it out

Zodot is available on the Godot Asset Store here, and it can also just be downloaded directly from Github here.

Follow me on Twitter to hear more about interesting Godot projects!

Typescript Code Generation

Jason — Wed, 24 May 2023 17:52:58 +0000

Do you ever wonder how to generate TypeScript code automatically?

Using the TypeScript Compiler API, we can leverage it's factory functions for writing scripts that can generate TypeScript code, based on any rules we want!

To get started, create a new project with npm init then install the "typescript" npm package with npm install typescript. Create a file index.mjs with touch index.mjs which will hold our code generation script.

Next, we want to figure out what kind of code we want to generate. For this example, we will generate the following function:

function add(a: number, b: number): number {
  return a + b;
}

This is a very simple example, but the concepts apply to any type of code you want to generate.

Inside index.mjs, import the "typescript" package and start exploring what is available in it via intellisense. For this example, we see that we will need to define a few "identifiers", specifically a, b and add. Those are all "names" and are represented by identifiers inside Abstract Syntax Trees.

We can start by defining each identifier at the top of our file using the factory method called createIdentifier:

const aId = ts.factory.createIdentifier("a");
const bId = ts.factory.createIdentifier("b");
const addId = ts.factory.createIdentifier("add");

We'll also need the number keyword a few times so we can add that right below the others:

const numberKeyword = ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword)

Then we can start creating the function declaration and use intellisense to figure out what needs to be provided:

const addFunc = ts.factory.createFunctionDeclaration(
  /* modifiers */,
  /* asteriskToken */,
  /* name */,
  /* typeParameters */,
  /* parameters */,
  /* type */,
  /* body */
)

We can see that it takes a few slots for different types of AST nodes. We'll need to use a few of them, and the others we can leave blank with an undefined value.

The first two, modifiers and asteriskToken we can leave blank since we don't need them here. The next one name we can use our addId we defined earlier. For typeParameters we can leave blank. For parameters, we'll need to define two, one for each parameter, using the identifiers we already created. For type we can use the numberKeyword we already defined, this represents the return type of the function. Finally, for body we will create a new block node that includes a return statement with a binary expression that adds the two parameters together.

There are a lot of technical terms here - for in-depth details on everything mentioned here, take a look at my new book "The Typescript Compiler API" that explains everything from A-Z for code generation, AST's and more!

Then to print it out, we can use a printer by doing:

function print(nodes) {
  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
  const resultFile = ts.createSourceFile(
    "temp.ts",
    "",
    ts.ScriptTarget.Latest,
    false,
    ts.ScriptKind.TSX
  );

  console.log(printer.printList(ts.ListFormat.MultiLine, nodes, resultFile));
}

print([addFunc]);

The final script should look like this:

import ts from "typescript";

const aId = ts.factory.createIdentifier("a");
const bId = ts.factory.createIdentifier("b");
const addId = ts.factory.createIdentifier("add");
const numberKeyword = ts.factory.createKeywordTypeNode(
  ts.SyntaxKind.NumberKeyword
);

const addFunc = ts.factory.createFunctionDeclaration(
  undefined,
  undefined,
  addId,
  undefined,
  [
    ts.factory.createParameterDeclaration(
      undefined,
      undefined,
      aId,
      undefined,
      numberKeyword,
      undefined
    ),
    ts.factory.createParameterDeclaration(
      undefined,
      undefined,
      bId,
      undefined,
      numberKeyword,
      undefined
    ),
  ],
  numberKeyword,
  ts.factory.createBlock(
    [
      ts.factory.createReturnStatement(
        ts.factory.createBinaryExpression(
          aId,
          ts.factory.createToken(ts.SyntaxKind.PlusToken),
          bId
        )
      ),
    ],
    true
  )
);

function print(nodes) {
  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
  const resultFile = ts.createSourceFile(
    "temp.ts",
    "",
    ts.ScriptTarget.Latest,
    false,
    ts.ScriptKind.TSX
  );

  console.log(printer.printList(ts.ListFormat.MultiLine, nodes, resultFile));
}

print([addFunc]);

When we run node index.mjs, we should see the following printed to the console:

function add(a: number, b: number): number {
    return a + b;
}

Congratulations, you just generated your first function! If you enjoyed this exercise and want to learn more about code generation, abstract syntax trees, linters, customer diagnostics in Typescript and more, then feel free to check out my new book that covers all of this in-depth. Cheers!

React Query Codegen from OpenAPI

Jason — Thu, 09 Jun 2022 19:50:53 +0000

Rapini is a new tool that can generate custom React Query hooks using OpenAPI (Swagger) files.

The Command Line Interface (CLI) tool will take a path to an Open API file and generate a package that includes react hooks, typescript types and axios http requests - and this package is conveniently bundled in a way that it can be published to NPM or any other package registry of your choosing.

No need to manually write axios request functions and react query code to start using your backend endpoints, just generate and import your code to ship features faster.

How to generate react hooks from Open API files

Using the rapini CLI, here is an example to generate your react query hooks, axios requests and typescript types from Open API.

# Install the CLI tool globally (need npm)
npm i -g rapini

# Pass the path to your Open API file to rapini
rapini -p path/to/openapi.yaml

And that's it! 1 command to install the CLI globally and 1 command to generate everything you will ever need.

The generated code will be outputted to rapini-generated-package folder in your current directory, but that could be changed with a CLI option --output-dir, like this: rapini -p path/to/openapi.yaml --output-dir /my-custom-package.

There are many CLI options to customize the generated code, including options for:

specifying the name and package version for the generated package's package.json file
specifying a base url for every request since it may not be included in the OpenAPI files
specifying replacers to customize the route used in the requests incase you may need to modify what's in the OpenAPI file without actually changing the OpenAPI file

All the options can be found on the rapini readme.

Why codegen React-Query with OpenAPI?

Code generation or codegen is a popular way to increase productivity, reduce bugs, and lower the amount of time it takes to ship features quickly.

OpenAPI already provides all the necessary information for writing code automatically, so we don't need to write the code manually anymore. We no longer need to manually write out the Typescript types for every requests payload and response, because they are already specified in the OpenAPI file. No longer do we need to write axios functions for every request, or react query hooks for every axios call.

Every GET request will get it's own React Query custom Query hook, and every non-GET, such as POST/PUT/PATCH/DELETE will get their own custom React Query Mutation hook.

Why codegen Axios requests with OpenAPI?

Rapini uses axios as it's main http client because of it's flexibility for request and response interceptors and global configs. Rapini takes an axios instance when initializing and uses that instance for all react query hooks under the hood.

React Query OpenAPI Codegen Example

Once you generate the custom npm package using rapini, you can start to import all the react query hooks, types, requests and query keys from the package. Let's say you generated your package with output name of my-package, like this: rapini -p path/to/openapi.yaml --output-dir /my-package then you can start importing like this:

import { initialize } from "my-package";
import type { Pet } from "my-package";
import { axiosInstance } from "./your-custom-axios-instance";

const rapini = initialize(axiosInstance);

const { queries, mutations, queryIds, requests } = rapini;

const MyComponent = () => {
  const { data, isLoading, isError } = queries.usePets();

  return (
    <ul>
      {data.pets.map((pet) => (
        <li key={pet.id}>{pet.name}</li>
      ))}
    </ul>
  );
};

Rapini uses the OpenAPI operationId to name all the hooks and requests in the code, so if you have a request with operationId like createPet, then an axios request will be made called createPet and react query mutation hook will be created called useCreatePet and a query key will be created called createPet, and all relevant request payload will be taken into account.

I hope you enjoy rapini and start deleting old code to replace with new generated code!

Traversing the C# Syntax Tree with F#

Jason — Thu, 09 Dec 2021 20:53:07 +0000

This article will go over the basics of the .NET compiler platform feature for analyzing the C# syntax tree, using F#.

.NET provides a Syntax API that can read any C# or Visual Basic source file and provide the corresponding Syntax Tree for that code.

Why

Why would someone need to traverse the C# syntax tree?

Well, it can be for a number of reasons, maybe you want to gather statistics about how many classes, namespaces and methods you have, maybe you want generate code based on what is already written, maybe you want to create new tools like a new linter or a tool like Swagger. All these things can be done by analyzing the syntax tree.

Recently I found myself using the Syntax API for finding Attributes above certain methods and classes, and based on the name and arguments of the Attributes, I generated various other files that were used elsewhere.

using System.Collections;
using System.Linq;
using System.Text;

namespace FunWithSyntaxTrees
{
    class Program
    {
        static void Main(string[] args)
        {
            // ...
        }
    }
}

The snippet above shows a small program. We will use this snippet as our input for analyzing the syntax tree.

How

Assuming you have an F# environment setup. You can begin by installing the nuget package Microsoft.CodeAnalysis.CSharp and importing that into your project.

open Microsoft.CodeAnalysis
open Microsoft.CodeAnalysis.CSharp
open Microsoft.CodeAnalysis.CSharp.Syntax

module Main =

  [<EntryPoint>]
  let main argv =
    0

After you install the package and add your open directives, we will hardcode the C# source code from above into the file, above the main entrypoint function.

// ... open directives

let code = """
using System.Collections;
using System.Linq;
using System.Text;

namespace FunWithSyntaxTrees
{
    class Program
    {
        static void Main(string[] args)
        {
            // ...
        }
    }
}
"""

module Main =

  [<EntryPoint>]
  let main argv =
    0

When you write a real program that uses the Syntax API, you will most likely be reading the C# source from files, like this let code = File.ReadAllText "/path/to/file", instead of hardcoding the string like we did, but for this tutorial it is fine for demonstration.

So we will begin by passing the string of C# source code to the Syntax API to be parsed, in return we will get the Syntax Tree that we can begin analyzing.

[<EntryPoint>]
let main argv =
  let syntaxTree: SyntaxTree = CSharpSyntaxTree.ParseText code

  0

Note: I will write out the Type's of all the variables, but it is unnecessary most of the time since F#'s type inference is very capable of inferring the type itself. Just like in C# when you use the var keyword, it is capable of knowing the underlying type, in F# this inference is even more powerful and applies to arguments, functions and everything in-between.

Now that the Syntax API has returned our needed Syntax Tree, we can begin travering it and exploring what it offers as data.

First let us get all the using directives in the file. We start by getting the root node of the file, then we iterate over all the child nodes inside the root node and find the ones that are the correct UsingDirective type.

[<EntryPoint>]
let main argv =
  let syntaxTree: SyntaxTree = CSharpSyntaxTree.ParseText code

  let rootNode: CompilationUnitSyntax = syntaxTree.GetCompilationUnitRoot()
  let rootNodeChildren: SyntaxNode seq = rootNode.ChildNodes()

  0

The rootNodeChildren variable holds all the child SyntaxNode's of the root node. The root node is basically the first node of the SyntaxTree which holds everything, and a SyntaxNode is the most general type of node.

We now need to iterate over these children to find the correct SyntaxNode for using directives since that is what we are looking for. We will declare a small helper function to help find them.

let usingDirectiveNode (node: SyntaxNode): UsingDirectiveSyntax option =
  match node with
  | :? UsingDirectiveSyntax as usingDirective -> Some usingDirective
  | _ -> None

[<EntryPoint>]
let main argv =
  let syntaxTree: SyntaxTree = CSharpSyntaxTree.ParseText code
  let rootNode: CompilationUnitSyntax = syntaxTree.GetCompilationUnitRoot()
  let rootNodeChildren: SyntaxNode seq = rootNode.ChildNodes()

  let usingDirectives: UsingDirectiveSyntax seq =
    Seq.choose usingDirectiveNode rootNodeChildren

  0

The new helper function usingDirectiveNode takes a generic SyntaxNode and checks if it is of the UsingDirectiveSyntax variety, if it is, it returns an F# Option type containing the using directive node.

Note: An F# Option type is a way to represent a "nullable" value, since there are no real null values in F#, nullable values are representated as Algebraic Data Types, such as the Option type.

We use the new helper function by mapping over every node and passing it to the function. We use Seq.choose to filter out any None types and keep all the Some types. It also unwraps the Some types so we can keep using them without Option mapping.

So Seq.choose is just a fancy way of doing Seq.map and then Seq.filter specifically with Option types since the type signature is ('T -> 'U option) -> seq<'T> -> seq<'U>.

Moving along, so now that we have a sequence of using directives in a variable, we can get the specific properties of a using directive. For now we wil just print them out as proof.

let usingDirectiveNode (node: SyntaxNode): UsingDirectiveSyntax option =
  match node with
  | :? UsingDirectiveSyntax as usingDirective -> Some usingDirective
  | _ -> None

[<EntryPoint>]
let main argv =
  let syntaxTree: SyntaxTree = CSharpSyntaxTree.ParseText code
  let rootNode: CompilationUnitSyntax = syntaxTree.GetCompilationUnitRoot()
  let rootNodeChildren: SyntaxNode seq = rootNode.ChildNodes()
  let usingDirectives: UsingDirectiveSyntax seq =
    Seq.choose usingDirectiveNode rootNodeChildren

  usingDirectives
    |> List.ofSeq
    |> List.map (fun u -> printfn $"{u.ToString()}")
    |> ignore

  0

The output of running our program would be:

using System.Collections;
using System.Linq;
using System.Text;

Pretty cool right? We analyzed our C# code and found our using directives and printed them out.

We can use that strategy to find anything in our code, including methods, method arguments, types, classes, interfaces, enums, comments, attributes, etc, everything!

If you found this useful, feel free to follow me on twitter at @rametta

Simple Remote Data in Typescript

Jason — Thu, 05 Nov 2020 16:41:34 +0000

Introducing Simple Remote Data (SRD), a Static Land compliant TypeScript library for managing state from remote sources.

SRD's top features are:

Only 549 bytes minified and gzipped, that is ridiculously small!
Built with Higher Kinded Types (HKT's) to allow Typescript to infer these complex disjoint union types.
Static Land compliant!
Made for React or any other JS based frontend framework.

What is a Remote Data type?

A Remote Data type is a kind of discriminate union type in functional programming for managing the state of some data that is retrieved remotely and asynchronously, such as http response data, websockets, server sent events, reading a file, or any other async IO.

Remote Data greatly simplifies the 4 states of any IO operation - initial state, loading state, failure state or success state, by combining them into one pure union so none of these states can overlap and cause impossible states.

Why would I use a Remote Data?

To simplify your state model and prevent impossible states! SRD allows us to perform safe and pure computations on our data without redundant null checks.

It also allows us to cleanly represent our state in our UI applications by providing functions such as match which is our pattern matcher utility.

How would I use a Remote Data?

Here is a popular use case in any React application - fetching data from somewhere and displaying it on screen, while also displaying loading states and error states if the fetch fails.

import React, { useState, useEffect } from 'react'
import { SRD, notAsked, loading, failure, success } from 'srd'

const App = () => {
  const [rd, setRd] = useState(notAsked())

  useEffect(() => {
    setRd(loading())
    fetch('...')
      .then((data) => setRd(success(data)))
      .catch((err) => setRd(failure(err)))
  }, [])

  return SRD.match({
    notAsked: () => <div>Empty</div>,
    loading: () => <div>Loading...</div>,
    failure: (err) => <div>{err}</div>,
    success: (data) => <div>{data}</div>,
  }, rd)
}

Without SRD, we would need to manually manage states for errors, loading and initial states separately - with SRD the code is a lot smaller, easier to follow and most importantly, safer.

What else?

SRD also provides a lot of great functions for accessing and modifying the data inside the Remote Data.

If we needed to modify the data inside a success we can use the popular map function to do so, it will allow us to run a function on the inside data without worrying if it's a success or not.

Here is a TypeScript React example for updating an object:

const [rdPerson, setPerson] = useState<RD<string, Person>>(notAsked())

useEffect(() => {
  setPerson(loading())
  fetch('...')
    .then((person) => setPerson(success(person)))
    .catch((err) => setPerson(failure(err.msg)))
}, [])

const doubleAge = (person: Person): Person =>
  ({ ...person, age: person.age * 2 })

const handleClick = () => {
  setPerson(rd => SRD.map(doubleAge, rd))
}

return <>
  {
    SRD.match({
      notAsked: () => 'Empty',
      loading: () => 'Please wait...',
      failure: (msg) => `There was a problem: ${msg}`,
      success: person => `My age is ${person.age}`
    }, rdPerson)
  }
  <button onClick={handleClick}>
    click to double my age
  </button>
</>

And map is not the only thing we can do, SRD provides over a dozen more utilities for managing your SRD state!

I hope this article clarified the advantages of using a Remote Data type and how to use SRD, I encourage you to try it out! If you do, feel free to "Star" 🌟 the repo on github!

5 reasons why Hugo is better than Gatsby

Jason — Sun, 16 Aug 2020 14:34:00 +0000

Hugo is an amazingly underrated static site generator and this post is aimed to provide some examples on why it may be a better choice than Gatsby for your next static site!

TLDR;

Hugo builds are way faster than Gatsby
Hugo's template system is simple
Hugo's built-in features are better than Gatsby's plugin features
Hugo doesn't require any JS to be used, but supports JS with ESBuild
Hugo has a small learning curve

1. Build Times

Gatsby

Gatsby is notorious for having long build times that depend on which plugins you use and amount of data you have in each page.

It is not unusual for Gatsby builds to take more than 20+ minutes to build a production site that only has a couple hundred pages. If you use popular plugins like gatsby-image, then expect your build times to skyrocket even higher.

If you use Gatsby's internal GraphQL implementation for saving and querying data nodes inside your pages, then expect longer build times as well.

Gatsby will promote their new incremental builds and cloud build capabilities, but they are marginally faster, buggy, and cause serious vendor lock-in to their Gatsby Cloud CI service.

Hugo

Hugo on the other hand, is known for it's extremely fast builds.

On average every page can be generated in less than 1ms, so a site with 10,000 pages can take just 10 seconds to build, whereas a Gatsby site with 10,000 pages, with the same amount of data, would take 30+ minutes or even hours to build.

Hugo also has native image processing similar to gatsby-image but is way faster and would marginally increase build time.

2. Templates

Gatsby

Gatsby is built on top of React, and therefore uses JSX as it's template system.

JSX is transformed into HTML at build time for the first page load and then re-rendered so Javascript can take control of all document nodes at runtime.
Using React and JSX for static sites, that don't necessarily need complex interactions and logic, means that you ship large JS bundles (that include the React library, Gatsby library, plugins, 3rd party npm libraries, polyfills and more) with every page - whereas the equivalent vanilla JS would most likely be a fraction of the size.

Computers or phones with low processing power or memory can struggle to display sites with large JS bundles and can feel laggy and unresponsive.

Hugo

Hugo uses the Go Template language for it's templates which has simple, easy to read syntax that doesn't require knowledge of JS to be written.

The Go Templates are converted to HTML at build time and if their is optional JS included on the page, it can be minified, inlined, and even compiled using ESBuild which is included in Hugo automatically.

3. Features

Gatsby is marketed to have a large amount of features that other static site generators do not have, largely attributed to it's plugin system. But even with Gatsby's plugin system, Hugo has all the important features built-in to it's core instead of needing to install it separately.

In one of Gatsby's thousands of marketing pages, they show a breakdown of Gatsby vs Hugo vs Jekyll and they show how Gatsby wins or ties in every category, but most of these comparisons don't make any sense or are completely false.

For example, Gatsby shows that Hugo has no modern javascript syntax even though Hugo has ESBuild which is orders of magnitudes faster than Gatsby's webpack implementation for compiling modern javascript syntax.

Another example is that Gatsby claims that Hugo does not have declarative data queries or UI building which is completely false. Hugo has data templates, data queries and components in the form of partials, inside of templates.

Also, Gatsby claims that Hugo doesn't have pair programming in it's community, which is false, Hugo has a discourse, and they say that Hugo has no swag store... Does that matter? who cares?

There are more examples in that chart of Gatsby trying to make themselves seem better but are just lying, and it'll take awhile to dispute all of them, so we will just move on.

4. JavaScript Support

Gatsby is built on top of React so it of course has JS support by using Webpack and Babel to compile down for browser support.

But as mentioned above, Hugo also has JS support by leveraging ESBuild, which is a JS bundler and minifier written in Go and is orders of magnitude faster than the Webpack and Babel combo.

Hugo also makes it way easier to code-split your JS code by just declaring which files you want loaded in each template. You can even include React if needed for more complex components.

Details here in their docs.

5. Learning Curve

Gatsby has an incredibly large learning curve, to get started writing useful Gatsby sites, one must know:

JS / NodeJS
JSX
NPM
React
GraphQL
Gatsby's complicated build system, transform plugins, source plugins, Gatsby Themes, Gatsby Recipes, and Gatsby's CLI
HTML
CSS
Markdown - optional

And some of those are very large topics, like React and GraphQL.

To get started with Hugo, one must know:

HTML
CSS
Hugo Template Syntax and Template Lookup order
Markdown - optional

It is a lot easier to get started with Hugo and scale out Hugo for complicated and large sites.

Honorable Mention

Gatsby is a for-profit business and will push their products like Gatsby Cloud on you even if there are better alternatives.

To learn more about Hugo, check out my mini course about it at hugo-mini-course.netlify.app

Using TypeScript ADT's to write more reliable React

Jason — Tue, 28 Jul 2020 17:18:31 +0000

You may have heard of Algebraic Data Types (ADT's) before but didn't understand how they can be applied to everyday code - so this article will provide some examples and explanations of why you should start using them.

Before we get into ADT's, let's go over the foundation of what ADT's are made of.

Basic Types

In Javascript, you can not declare a type that prevents other types from being assigned to it. The below example we see that anything can be assigned to the language variable. We can assign a number or a boolean or an object to it if we later wanted, but that may cause bugs in the future if we were not expecting the variable type to be something other than a string.

let language = 'en'

In Typescript, we get more control over declaring types. See below, now we can only assign a string to the language variable, which is much better. Now when we access this variable in the future, we are pretty certain that the value will be a string and proceed accordingly.

let language: string = 'en'

But we can do better...

Union Types

With Typescript Union Types, we can say something can be more than one type. 😮 In the below example, we see that the language variable can either be a string OR a number.

let language: string | number = 'en'

You might be saying to yourself, "cool, but why would I want two different types in one variable?"

This is a great question, but before we figure out why we would need this, we need to understand that anything can be considered a type in Typescript, including specific string values.

So now we can specify exactly which values can be assigned to the language variable.

let language: 'en' | 'fr' | 'ru' = 'en'

Now we can only assign certain values to language.

The interesting question now is, "how do we know which type is currently stored?"

If we have a variable that can hold two different types, when we access that value, we must check to see what the type is before we do something with it.

let nameOrID: string | number = 'Jason'

if (typeof nameOrID === 'string') {
  // do something with string...
} else if (typeof nameOrID === 'number') {
  // do something with number...
}

This is important, because if we do not check the value type then we do not know which one of the types is currently being used - so we might try to do math with a string, or do a string operation on a number...

Knowing these things, now we can explain Typescript's Discriminated Union Type.

Discriminated Union Types

Using the things we learned about Union Types, we can construct a special union that obeys some rules.

The rules that should be followed are:

All types in the union, share a common property.
There needs to be a union type declared from the types.
There must be type guards on the common property.

Here is an example:

type HockeyGame = {
  kind: 'hockey' // Rule 1 - common property 'kind'
  homeScore: number
  awayScore: number
  clock: number
  isDone: boolean
}

type BaseballGame = {
  kind: 'baseball' // Rule 1 - common property 'kind'
  inning: number
  isTop: boolean
  stadium: string
}

// Rule 2 - Union type declared
type Game = HockeyGame | BaseballGame

const gameToString = (game: Game): string => {
  // Rule 3 - Type guard on the common property
  switch (game.kind) {
    case 'hockey':
      return `Hockey game clock: ${game.clock.toString()}`
    case 'baseball':
      const frame = game.isTop ? 'top' : 'bottom'
      return `Baseball game is in the ${frame} of inning ${game.inning}`
  }
}

In the example above, we see that we used what we learned about assigning specific strings to a type with the kind property. The kind property can only ever be hockey or baseball and never anything else.

This common property acts as an ID for the object and allows us to know what other properties are defined and available to be accessed.

Following these rules will allow the Typescript compiler to know which fields are available. So if you have checked the guard and deemed it to be hockey then the compiler will only allow you to access the fields from the HockeyGame type.

This can prevent a lot undefined errors you may get from accessing properties that may or may not be there at different times.

ADT's with React

Now let's see how we can take advantage of this pattern in React.

Using the Game types declared above, we can safely render different components based on the common property in the union.

const HockeyGameBox = ({ game }: { game: HockeyGame }) => (
  <div>
    {game.homeScore} - {game.awayScore}
  </div>
)

const BaseballGameBox = ({ game }: { game: BaseballGame }) => (
  <div>
    {game.inning} - {game.stadium}
  </div>
)

const renderGame = (game: Game) => {
  switch (game.kind) {
    case 'hockey':
      return <HockeyGameBox game={game} />
    case 'baseball':
      return <BaseballGameBox game={game} />
  }
}

const GamePage = () => {
  const [games] = useState<Game[]>([
    /* mix of different games */
  ])
  return games.map(renderGame)
}

As you can see, using ADT's can greatly reduce the amount of runtime bugs you get when using dynamic data. It's not a silver bullet for preventing bugs, but it's a step in the right direction.

To learn more about ADT's, check out my post about it in Elm: Elm's Remote Data Type in Javascript

Introducing Yokie - A Recipe Sharing Social Media WebApp

Jason — Mon, 20 Apr 2020 23:29:33 +0000

I would like to share a small project I've been working on for the past few days. Yokie!

Yokie is a recipe site that I always wanted but was never able to find.
Most cooking recipe sites out there are slow, full of ads, and have a giant story or description before actually seeing the recipe, so Yokie's mission is to:

Provide the ingredients and directions at the top of every recipe
Load adequately fast
Be ad-free

Along with those core competencies, Yokie also provides:

A grocery list feature that is shareable and editable with other users
A favoriting feature to keep track of recipes you want to remember to cook
A profile to showcase your own recipes (or store your private recipes)

I built this app because it's something I wanted to use everyday. I figured others might also not enjoy the current landscape of recipe sites out there, so decided to make it a social media site so anybody can join and start searching and saving their recipes too.

The tech stack

The stack is pretty cool in my opinion, nothing too fancy, most pages are server rendered using Go templates, and most pages have little or no javascript on them!

2 pages are pretty interactive so I added VueJS to those pages, 'why Vue?' you may ask, because I didn't want to setup any bundling or a client side compiling workflow, with Vue I just needed to add a script tag and start using it - easy peezy.

All data is stored in a Firestore database, and all recipes are also stored in Algolia in order to have a nice search page.

Authentication is handled with Firebase Auth because it's free and it just works.

The Go server runs on Google App Engine, and user files are stored in Google Storage.

And that's pretty much it!

Signup!

I'm trying to get people to signup so the database of recipes starts to grow, so I'm offering a twitter style verification checkmark for new users for awhile - so if you want to secure your favorite username and get a nice cool checkmark on your profile - signup!

Cheers!🍻

Lessons learned from my first 10k LOC in Elm

Jason — Thu, 24 Oct 2019 15:16:20 +0000

I have been working on a personal project of mine for the last couple of months that has the frontend written in Elm. So far everything is going great and the project is around 10k lines of code.

I have noticed a few reoccurring patterns of mine that I have learned so far and want to share, so here are 5 things I have learned:

1. Decoding Empty Lists & Strings

When I first started the project, I had a lot of types with fields declared like this:

type alias Something =
  { name : Maybe String
  , stuff : Maybe (List String)
  }

and the way I was decoding these values from my API was like this:

import Json.Decode as D
import Json.Decode.Pipeline exposing (optional)

D.succeed Something
  |> optional "name" (D.nullable D.string) Nothing
  |> optional "stuff" (D.nullable (D.list D.string)) Nothing

This was fine at first, but I noticed that after awhile I was repeating logic inside my update functions to check if the name field was an empty string, or if the stuff field was an empty list, and if it was, change the value to Nothing instead of Just "" or Just [].

So after awhile, I thought it would be more efficient to check for empty strings and empty lists during the decoding phase, so I came up with two decoder helper functions, decodeNonEmptyString and decodeNonEmptyList:

decodeNonEmptyString : D.Decoder (Maybe String)
decodeNonEmptyString =
  D.andThen (notEmptyString >> D.succeed) D.string

decodeNonEmptyList : D.Decoder a -> D.Decoder (Maybe (List a))
decodeNonEmptyList l =
  D.andThen (notEmptyList >> D.succeed) (D.maybe (D.list l))

notEmptyList : Maybe (List a) -> Maybe (List a)
notEmptyList =
  Maybe.andThen (\l ->
    if List.isEmpty l then
      Nothing
    else
      Just l
  )

notEmptyString : String -> Maybe String
notEmptyString s =
  if String.isEmpty s then
      Nothing
  else
      Just a

So now my original decoders use these new utilities like this:

D.succeed Something
  |> optional "name" decodeNonEmptyString Nothing
  |> optional "stuff" (decodeNonEmptyList D.string) Nothing

And I don't need to check for emptiness anymore in my update functions 🎉

2. Flatter pattern matching

This one might seem really obvious, but took me awhile to realize that doing this results in flatter pattern matching functions.

If I have a type like RD.WebData (Maybe (List Person)), the way I original matched on it was like this:

case response of
  RD.NotAsked -> div [] [text "Not Asked"]
  RD.Loading -> div [] [text "Loading"]
  RD.Failure e -> div [] [text "Error"]
  RD.Success maybeData ->
    case maybeData of
      Nothing -> div [] [text "No data"]
      Just data -> div [] [text "Data!"]

But I realized that I could flatten this into one case statement instead of 2 separate ones like this:

case response of
  RD.NotAsked -> div [] [text "Not Asked"]
  RD.Loading -> div [] [text "Loading"]
  RD.Failure e -> div [] [text "Error"]
  RD.Success Nothing -> div [] [text "No data"]
  RD.Success (Just data) -> div [] [text "Data!"]

See? Much nicer!

3. Select Wrapper

This is one of the first abstractions I made when I started because I wanted an easy reusable way to use select [] [] and found that the native one in Elm is not as nice as I hoped.

So I wrote a small wrapper called viewSelect:

viewSelect : Bool -> (String -> msg) -> List Option -> Html msg
viewSelect disabled changeMsg options =
  select
    [ onChange changeMsg
    , Html.Styled.Attributes.disabled disabled
    ]
    (List.map
      (\opt ->
        option
          [ value opt.value
          , Html.Styled.Attributes.selected opt.selected
          , Html.Styled.Attributes.disabled opt.disabled
          ]
          [ text opt.text ]
      )
      options
    )

type alias Option =
  { text : String
  , value : String
  , selected : Bool
  , disabled : Bool
  }


onChange : (String -> msg) -> Html.Styled.Attribute msg
onChange tagger =
  on "change" (D.map tagger Html.Styled.Events.targetValue)

Now I use viewSelect instead of the native select and I just need to pass in a list of Option instead. Every time a user changes the select box, the changeMsg fires with the new value.

4. ChangeField Pattern

In my app, I have a lot of forms, and every form needs to modify some field inside my model. The way I originally started doing this was:

type Msg
  = ChangeName String
  | ChangeAge String
  | ChangeHeight String
  | ChangeWeight String

update msg model =
  case msg of
    ChangeName name -> ({ model | name = name }, Cmd.none)
    ChangeAge age -> ({ model | age = age }, Cmd.none)
    ChangeHeight height -> ({ model | height = height }, Cmd.none)
    ChangeWeight weight -> ({ model | weight = weight }, Cmd.none)

This was also fine at first, but my app has A LOT of forms and this was not scaling well. So instead of creating a new Msg type for every field, I created one Msg type for updating any field. And it works like this:

type Msg = ChangeField (String -> Person -> Person) String

update msg model =
  case msg of
    ChangeField setter content -> (setter content model, Cmd.none)

Now every time a field needs to change, instead of calling ChangeName "Jason", I can now call ChangeField setName "Jason" where setName equals:

setName : String -> Person -> Person
setName content person =
    { person | name = content }

This allows me to create individual setter functions for each field and do any data manipulations from String into any type I need.

It simplifies my update function by reducing the amount of Msg types it can match on, and it nicely separates out my data manipulation logic for each field.

5. Posix Wrappers

This one is pretty simple really. I use Elm's Time.Posix type a lot around my app, so I needed functions to format, manipulate and display Posix in my UI. I came up with a few helpers for this and call it my HumanTime module:

humanDateTime : Zone -> Posix -> String
humanDateTime z p =
  humanDate z p ++ " " ++ humanTime z p

humanTime : Zone -> Posix -> String
humanTime z p =
  humanHour z p ++ ":" ++ humanMinute z p

humanDate : Zone -> Posix -> String
humanDate z p =
  humanMonth z p ++ " " ++ humanDay z p ++ ", " ++ humanYear z p

humanYear : Zone -> Posix -> String
humanYear z =
  toYear z >> String.fromInt

humanDay : Zone -> Posix -> String
humanDay z =
  toDay z >> String.fromInt

humanHour : Zone -> Posix -> String
humanHour z =
  toHour z >> String.fromInt

humanMinute : Zone -> Posix -> String
humanMinute z =
  toMinute z
      >> (\m ->
            if m > 9 then
              String.fromInt m
            else
              "0" ++ String.fromInt m
         )

humanMonth : Zone -> Posix -> String
humanMonth z p =
  case toMonth z p of
    Jan -> "Jan"
    Feb -> "Feb"
    Mar -> "Mar"
    Apr -> "Apr"
    May -> "May"
    Jun -> "Jun"
    Jul -> "Jul"
    Aug -> "Aug"
    Sep -> "Sep"
    Oct -> "Oct"
    Nov -> "Nov"
    Dec -> "Dec"

And that is it so far! I am sure I will learn even more in the next 10k LOC that I write and might even figure out better ways of doing these things that I just mentioned.

Elm is an amazing tool for creating frontends and I can't ever see myself going back to React or any other non-functional frameworks for personal projects.

If you liked this article, be sure to follow me on DEV to see whenever I post new articles in your feed ✨ or follow me on twitter!

Pratica - Monadic Library, now fully in Typescript!

Jason — Fri, 18 Oct 2019 15:28:08 +0000

Pratica is now written completely in Typescript!

What is Pratica?

Pratica is a super tiny 720B monadic library, comparable to Crocks or Monet JS.

Why would I use Pratica?

If you want to start writing more functional code in Javascript or Typescript, this is a great library for learning some FP fundamentals, while also making your code safer and more resilient to runtime bugs. It's super tiny size and easy to read dot-chaining syntax makes it easy to get started in any project.

How do I start?

You can install it with: yarn add pratica or npm i pratica. Then you can import the main functions like:

import { nullable } from 'pratica'

Create small, safe and easy to read programs by composing functions together, like:

// Typescript

import { Maybe, nullable, get, parseDate } from 'pratica'

const getPersonAge = (person?: Person): Maybe<number> =>
  nullable(person)
    .chain(get<string>(['birthday']))
    .chain(parseDate)
    .map(birthday => Date.now() - birthday.getTime())
    .chain(parseDate)
    .map(date => Math.abs(date.getUTCFullYear() - 1970))


getPersonAge({ birthday: '1994-06-08' }) // -> Just(25)
getPersonAge({ birthday: 771033600000  }) // -> Just(25)
getPersonAge({ birthday: null }) // -> Nothing
getPersonAge(null) // -> Nothing

Pratica works great with React too! Use it in your JSX for handling cases with missing data.

const viewPersonAge = ({ person }) =>
  getPersonAge(person).cata({
    Just: age => <div>{age}</div>
    Nothing: () => <span>No age available</span>
  })

Try it out

Try it out in an online browser sandbox here!

or check it out on Github below!

rametta / pratica

🥃 Functional Algebraic Data Types

🥃 Pratica

Functional Programming for Pragmatists

Why is this for pragmatists you say?

Pratica sacrifices some common FP guidelines in order to provide a simpler and more approachable API that can be used to accomplish your goals quickly - while maintaining data integrity and safety, through algrebraic data types.

Install

bun i pratica
# or
yarn add pratica
# or
npm i pratica

Documentation

Monads

Maybe

Use this when dealing with nullable and unreliable data that needs actions performed upon.

Maybe is great for making sure you do not cause runtime errors by accessing data that is not there because of unexpected nulls or undefineds.

Every Maybe can either be of type Just or Nothing. When the data is available, it is wrapped with Just, if the data is missing, it is Nothing. The examples below should clarify futher.

Maybe.map

Map is used for running a function…

View on GitHub

Elm's Remote Data Type in Javascript

Jason — Fri, 26 Jul 2019 13:42:11 +0000

Often in web development there is this recurring pattern of having to fetch some data from some server through a rest api, and then show it someway in the UI.

This often includes storing this data somewhere on the client side, either in a store or just a variable you can reference, and this is where the Remote Data type can help.

Usually saving the data would look something like this in JS:

// Javascript

const state = {
  data: null,
  error: null
}

fetch('/api/data')
  .then(res => res.json())
  .then(data => state.data = data)
  .catch(err => state.error = err)

and showing it on screen:

// React

const MyComp = ({ error, data }) => {
  if (error) {
    return <div className="error">{error}</div>
  } else {
    return <div>{data}</div>
  }
}

But there are a few problems with this approach:

What do we show on screen when the data is loading from the server?
What do we show on screen before we even request the data from the server?
Do we properly clear the previous error if the data is a success?
Do we properly clear the previous data if we get an error?

So how can we solve this?

Some might recommend we can add more fields to our state to help represent all the cases, like this:

// Javascript

const state = {
  data: null,
  error: null,
  loading: false,
  isAsked: false
}

and in the UI would be similar to this:

// React

const MyComp = ({ error, data, loading, isAsked }) => {
  if (!isAsked) {
    return <div>Nothing asked yet</div>
  }

  if (loading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div className="error">{error}</div>
  }

  if (data) {
    return <div>{data}</div>
  }

  return <div>Some default fallback to be safe</div>
}

But the problem with this is that it becomes too easy for our UI to accidently show the wrong case by forgetting to set loading to false after the data comes back as an error, or forgetting to clear the error if a retry returned a success.

Infact, optimistically the structure above can have a cardinality of 2 x 2 x 2 x 2 which is 16 possible different combinations of states we can be in at any given time. That is a lot of cases to represent.

Let's look at how Elm simplifies this process with needing only 4 cases.

Remote Data in Elm

The Remote Data type can be created manually by writing a custom type like below, or by using a pre-made version from a library like krisajenkins/remotedata:

-- Elm

type RemoteData e a
  = NotAsked
  | Loading
  | Error e
  | Success a

and then using this type as your model:

-- Elm

type alias Model = RemoteData String MyData

-- and set the initial model value as NotAsked

init = NotAsked

What we need to understand is that our state can only be one of these 4 types at any time. We can not both be in a Loading state and in a Success state at the same time, or else our UI will be showing 2 different things. This is why our cardinality is only 4 now instead of 16, because there is no way to represent our state more than that.

Using this model we can now create a UI for each case like this:

-- Elm

view model =
  case model of
    NotAsked -> div [] [ text "Not asked yet" ]

    Loading -> div [] [ text "Loading..." ]

    Error err -> div [] [ text err ]

    Success data -> div [] [ text <| "Here is my data: " ++ data ]

And now whenever we update our state, we never need to worry about clearing previous state or forgetting to flip one field to null - because there is only one field in our model.

This is a great pattern for handling remote data fetching in Elm, but how do we take advantage of this pattern in Javascript? Daggy.

Daggy

There are a few different libraries in Javascript that can help model your application with Algebraic Data Types like we have in Elm with the type keyword. One popular library is Daggy.

To represent remote data in Daggy, we would create a type like this:

// Javascript

import { taggedSum } from 'daggy'

const RemoteData = taggedSum('RemoteData', {
  NotAsked: [],
  Loading: [],
  Error: ['e'],
  Success: ['a']
})

Then once we have our type, the implementation is almost identical to how we would work in Elm.

Our state would only have one field instead of 4, and a cardinality of 4 instead of 16.

// Javascript

const state = {
  data: RemoteData.NotAsked
}

// Fetch some data

state.data = RemoteData.Loading

fetch('/api/data')
  .then(res => res.json())
  .then(data => state.data = RemoteData.Success(data))
  .catch(err => state.data = RemoteData.Error(err))

And in our UI, like React, we would have:

// React

const MyComp = ({ data}) => data.cata({
  NotAsked: () => <div>Not asked yet</div>,
  Loading: () => <div>Loading...</div>,
  Error: err => <div>{err}</div>,
  Success: d => <div>Here is my data: {d}</div>
})

Using this pattern actually helps move a lot of render logic out of your components in React, like checking fields with if (field) {...} and instead moves that responsibility to something like a reducer, which will make it a lot easier to run unit tests on.

If you would like to learn more about Algebraic Data Types in Javascript, check out these links:

If you like this article, be sure to follow me!