Forem: Caleb Adepitan

Handling OAuth 2 Sign-In and Sign-Up Distinctly with NextAuth.js

Caleb Adepitan — Mon, 25 Dec 2023 19:26:23 +0000

Authentication, authorization, access control, and any other synonymous name you can think to call it, is not always a walk in the park. Through the evolution of the World Wide Web (WWW) and web applications, there have been various solutions to help make authentication a breeze. There have been, third-party services like Auth0 that you can easily integrate with your apps without having to worry much about authentication and doing it right, or worry about security because these third-party services cover all of that. There have also been standards, and specifications like OAuth and OpenID Connect (OIDC) which have evolved over the years. Some libraries and SDKs enable developers to easily integrate with these services, standards and specifications without worrying much about low-level implementation details. The only need-to-know is a subset of the SDK’s APIs needed to meet the application requirements. NextAuth.js is one of these libraries!

I think it’s bad UX to implicitly create an account for a user when they only wish to sign in. NextAuth.js provides no distinction between authenticating an existing user and registering a new user when using the OAuth flow with any of the available providers.

NextAuth.js is a complete open-source authentication solution for Next.js applications. It is designed from the ground up to support Next.js and Serverless. https://next-auth.js.org/getting-started/introduction. This library makes integrating with several OAuth 2.0 providers, like Google, Apple, Facebook, Twitter (X), etc, a breeze.

So what’s the problem?

The problem is that I searched every nook and cranny in this library for a signUp function just like there’s a signIn function and a signOut function, but I couldn’t find a single one.

It’s expected that every application that has a way to sign in, should have a way to sign up. Sometimes, the sign-up flow isn’t always obvious, especially when working with internal applications where there’s a central admin that manages user’s accounts. The admin mostly creates the account (sign up), and gives the user the credentials, while also prompting them to change their password on their first sign-in.

So why is there no signUp function?

Because the signUp function is an easter egg and no one has found it yet!

A high-level view of the OAuth 2.0 flow

Well it’s thought that when a user follows the OAuth flow, say, using one of the providers like Google, they start with clicking a button that probably says, “Sign in with Google”, then get redirected to a Google accounts page where they are required to sign in to their Google account or, if they are already signed in, they see a list of their signed-in accounts and choose one of them, then get redirected back to the originating page—at least that’s what the user sees.

What happens when this user doesn’t have an existing account on the first-party app matching the returned email from Google, are we supposed to tell them “Account not found” or go ahead and implicitly create an account for them on our (first-party) app?

It would seem the latter is the case when using NextAuth.js: if there’s no account found by the returned email address from Google, sign up the user immediately without wasting time because we need to convert, and that’s a plus one DAU or MAU or whatnot.

This is a bad UX!

Why I think this is a bad UX

Oftentimes I come back to an application after not using it for a while or after not having to sign in for a while because I had a very long session before I was eventually logged out, and I can’t remember how exactly I created an account, whether I used regular email and password credentials, “Sign in with Google”, “Sign in with Apple”, etc. I can’t remember.

I go ahead and guess the authentication method I used, I decide it was “Sign in with Google”. So I click the “Sign in with Google” button and choose one of my Google accounts. But, whoops, it wasn’t Google—a new account has, inadvertently, been created for me on the same app.

How did I know it’s a new account?

Are you really asking :(

So I try again, just this time, with more certainty that my original account is using “Sign in with Apple”. Thankfully, it sure is. What am I to do with the new account I just created?

I mentioned this in an age-old discussion on NextAuth GitHub repo.

Figuring a way out of this bad UX

We should understand the NextAuth.js flow for OAuth 2.0 flow. There’s an illustration on this linked page that lays out the flow.

In a nutshell, it goes to our /api/auth/signin/[provider] route handler first, then redirects to that specific provider page for you to complete the authentication, the provider then redirects to our /api/auth/callback/[provider] handler with some extra params about the authentication.

1. Using `SignInOptions`

First, I thought there should be a way to pass some custom options to the signIn function that would be accessible from the callbacks, since the callbacks is where you do all the nifty tricks needed by your application.

// :title=SignUpPage.tsx

signIn('google', { intent: 'signup' })

That was a dumb one! Calling that function with a provider other than "credentials" or "email" will redirect to the external provider. It doesn’t immediately trigger any callback or a function like authorize, as in CredentialsProvider, defined in our nextAuthOptions object. By the time the two-way redirect is complete, our initial context is lost.

2. Using the `referer` header

Another solution I thought of was to intercept the Next.js route handler (Next.js 13 route handler in my case) before passing the request to the NextAuth factory function and read the headers to check for the referer header. If it matches the route of my sign-up page then it’s a sign-up the user intends, otherwise, it’s a sign-in that the user intends.

// :title=./api/auth/[...nextauth]/route.ts

import { NextApiRequest, NextApiResponse } from 'next'
import NextAuth from 'next-auth'
import { headers } from 'next/headers'

// assuming a `Routes` object that contains an enumeration of all or most routes in our app
// assuming some arbitrary `getAuthOptions` factory function returning the NextAuth config options

type AuthIntent = 'signin' | 'signup' // signin or signup

const Routes = { SIGNUP: '/auth/signup', ..., };

function getAuthOptions(intent: AuthIntent) {...}

async function handler(req: NextApiRequest, res: NextApiResponse) {
  const headersList = headers()
  const referer: string | null = headersList.get('referer') // https://hostname.tld/auth/signin
  const intent = referer && new URL(referer).pathname === Routes.SIGNUP ? 'signup' : 'signin'
  return await NextAuth(req, res, getAuthOptions(intent))
}

export { handler as GET, handler as POST }

This is also flawed for two reasons.

There’s not enough control over who can set the referer header and it’s not always guaranteed to be present so the referer header can sometimes be empty or may contain some unexpected value.
Remember there’s a redirect to Google from our handler and from Google back to our handler. At the time we need the referer header set to one of sign-in or sign-up routes, is when our handler is redirected to, from Google, and obviously, Google didn’t even set a referer, even if they did it wouldn’t be any of our expected routes.

What other tricks can a developer draw from their book of tricks?

How about a hat trick?

Well, the third time is the charm!

3. Using good ol’ cookies

Not that I didn’t think of cookies earlier, it just didn’t seem like the best approach at the time. But since I couldn’t figure out anything better that works, I had cookies as my fallback. Using cookies, we don’t need to change much of what we had with the referer header in the route handler.

// :title=./api/auth/[...nextauth]/route.ts

import { NextApiRequest, NextApiResponse } from 'next'
import NextAuth from 'next-auth'
- import { headers } from 'next/headers'
+ import { cookies } from 'next/headers'
+ import type { RequestCookie } from 'next/dist/compiled/@edge-runtime/cookies';

// assuming a `Routes` object that contains an enumeration of all or most routes in our app
// assuming some arbitrary `getAuthOptions` factory function returning the NextAuth config options

type AuthIntent = 'signin' | 'signup' // signin or signup

- const Routes = { SIGNUP: '/auth/signup', ..., };

function getAuthOptions(intent: AuthIntent) {...}

async function handler(req: NextApiRequest, res: NextApiResponse) {
-  const headersList = headers()
-  const referer: string | null = headersList.get('referer') // https://hostname.tld/auth/signin
-  const intent = referer && new URL(referer).pathname === Routes.SIGNUP ? 'signup' : 'signin'
+  const cookieStore = cookies()
+  const authIntent: RequestCookie | undefined = cookieStore.get('auth-intent')
+  const intent = (authIntent?.value ?? 'signin') as AuthIntent
  return await NextAuth(req, res, getAuthOptions(intent))
}

export { handler as GET, handler as POST }

Now that we have this on the server, how, where, and when do we exactly set this cookie we are getting here right now?

We set this cookie in the respective pages just as immediately as the page is rendered on the client.

A notable library to use to deal with cookies on the browser is js-cookie.

yarn add js-cookie
# or
npm install js-cookie

Into the Mire

It’s time to get our hands dirty. I’ve intentionally kept the code snippets short and simple rather than writing the entire implementation. But I guess now is the time to put it all together. Yet, I’ll be omitting some stuff, like JSX for pages, and go straight to the logic needed to show you the crux of this article, as this is not a tutorial on how to build authentication pages.

I hate to write snippets with undefined references, but this is me letting you know upfront that there may be undefined references in this one if I think a pseudo-code is enough or the references are such that, however you write your implementation is up to you.

If you’ve been with me until this point and you know what you are doing, you probably have all you need already and may not need the following sections. But if you are still trying to figure things out, you may proceed, read on, to get an idea of my implementation with the hopes that it helps bake yours.

Our sign-up and sign-in logic will look like the following:

// :title=SignUpPage.tsx

'use client';

import { useEffect } from 'react'

import Cookies from 'js-cookie';
import { signIn } from 'next-auth/react';

import { AppleButton, GoogleButton } from '@/components/buttons';
import { createAccountService } from '@/services/account';

export const SignUpForm = () => {
  useEffect(() => {
    // highlight-next-line
    Cookies.set('auth-intent', 'signup');
    return () => Cookies.remove('auth-intent');
  }, []);

  const handleSubmit = async (e: SubmitEvent) => {
    // Handle credential flow submission here and send data to your API
    const form = new FormData(e.target); // You're probably going to use `useState` or react-hook-form
    // highlight-start
    await createAccountService({ first_name: form.get('username'), ... });
    await signIn('credentials', { email: form.get('email'), password: form.get('password') });
    // highlight-end
  }

  return (
    <form onSubmit={handleSumbit}>
      <GoogleButton type="button" onClick={() => signIn('google')}>
        Sign up with Google
      </GoogleButton>

      <AppleButton type="button" onClick={() => signIn('apple')}>
        Sign up with Apple
      </AppleButton>

      {/* Other form inputs will go somewhere here */}
    </form>
  );
};

You may not need NextAuth.js to handle your credentials sign-up flow where users have to enter first name, last name, email, password, etc. For the sign-up, NextAuth.js is handling the OAuth flow only.

Looking at the highlighted lines, after setting the cookie, we have a credentials sign-in following the call to createAccountService because I’m assuming createAccountService doesn’t return a session token, just the newly created user account object. So we have to follow up with a sign-in to get the session tokens. If your API returns session tokens when registering a user, you may move your user registration logic into the NextAuth.js flow (inside your auth options file, options.ts) so you can add those tokens to your NextAuth.js session without having to sign in again after registering.

You are probably thinking that the auth-intent cookie is set to "signup", and it would affect the call to signIn following it. No, it won’t. The cookie is only needed by the OAuth flow but we are using the credentials flow here. But, again, if your API for registering users returns session tokens and you are handling your registration inside NextAuth.js, yes, this cookie may be necessary for your credentials flow, except you choose a different method to distinguish a sign-in from a sign-up, since you can pass data directly to your credentials provider handler using the signIn function.

Soon we’ll define the auth options which will contain the core logic. But first, let’s talk about the sign-in page and the sign-in form:

// :title=SignInPage.tsx

'use client';

import { useEffect } from 'react'

import Cookies from 'js-cookie';
import { signIn } from 'next-auth/react';

import { AppleButton, GoogleButton } from '@/components/buttons';

export const SignInForm = () => {
  useEffect(() => {
    // highlight-next-line
    Cookies.set('auth-intent', 'signin')
    return () => Cookies.remove('auth-intent');
  }, []);

  const handleSubmit = async (e: SubmitEvent) => {
    // Handle credential flow submission here and send data through NextAuth.js
    const form = new FormData(e.target); // You're probably going to use `useState` or react-hook-form
    // highlight-next-line
    await signIn('credentials', { email: form.get('email'), password: form.get('password') });
  }

  return (
    <form onSubmit={handleSumbit}>
      <GoogleButton type="button" onClick={() => signIn('google')}>
        Sign in with Google
      </GoogleButton>

      <AppleButton type="button" onClick={() => signIn('apple')}>
        Sign in with Apple
      </AppleButton>

      {/* Other form inputs will go somewhere here */}
    </form>
  );
};

It’s okay, in fact encouraged, to handle your credentials sign-in flow where users have to enter username or email, and password with NextAuth.js. For the sign-in, NextAuth.js is handling both the OAuth flow and the credentials flow.

Easy-peasy, nothing much to see here, we just had to call the sign-in function with the correct data, and oh, yes, set our auth-intent cookie.

Now back to our route handler. Applying our patch from above.

// :title=./api/auth/[...nextauth]/route.ts

import { NextApiRequest, NextApiResponse } from 'next';
import NextAuth from 'next-auth';
import { cookies } from 'next/headers';

// highlight-next-line
import type { RequestCookie } from 'next/dist/compiled/@edge-runtime/cookies';

import { getAuthOptions } from './options';

async function handler(req: NextApiRequest, res: NextApiResponse) {
  const cookieStore = cookies();
  const authIntent: RequestCookie | undefined = cookieStore.get('auth-intent');
  const intent = (authIntent?.value ?? 'signin') as AuthIntent;
  return await NextAuth(req, res, getAuthOptions(intent));
}

export { handler as GET, handler as POST };

The highlighted import statement above isn’t necessary. It’s only there for the sake of this article so you know authIntent could be either that type or undefined

We read the auth-intent from the request cookies to our route handler, which intercepts the NextAuth.js route handler, and pass it as an argument to the getAuthOptions factory function.

We should talk about the getAuthOptions factory function which we define in our options.ts file. For our options.ts file, we’ll write it chunk by chunk because it’s quite long. We start with defining some imports. It is assumed that we have some service functions that we can use to send a request to our API on the backend:

The authenticateAccountService is a service used to authenticate a user using the credentials flow, i.e., email, and password.
The authenticateAccountOIDCService is used to authenticate a user using an OAuth with OpenID Connect flow, i.e., access_token, and id_token (for Google).
The createAccountOIDCService is used to create a user using an OAuth with OpenID Connect flow, i.e., access_token, and id_token (for Google).
The identifyUserAccountService is used to fetch the user object provided that an access token granted by our application is present.

// :title=options.ts

import { AuthOptions, DefaultSession, Session } from 'next-auth';
import { JWT } from 'next-auth/jwt';
import CredentialsProvider from 'next-auth/providers/credentials';
import GoogleProvider from 'next-auth/providers/google';
import { BuiltInProviderType } from 'next-auth/providers/index';

import { authenticateAccountService, authenticateAccountOIDCService } from '@/services/account';
import { createAccountOIDCService, identifyUserAccountService } from '@/services/account';
import { type SigninCredentials, type UserAccountResponse } from '@/services/account';

Let’s take a short break from the options.ts file. We are going to do some declaration merging to make sure the shape of NextAuth.js objects fits our needs. A guide is also available in the NextAuth.js documentation.

// :title=types.ts

import { DefaultSession } from 'next-auth';

export interface AppToken {
  id: string // user account id
  type: string // Bearer
  access_token: string
  refresh_token: string
}

export interface AppSessionUser extends NonNullable<DefaultSession['user']> {
  /** @note This is the user account ID generated by the application itself not `providerAccountId` */
  id?: string;
  /** @note This is the token generated by the application itself not any 3rd party */
  tokens?: AppToken;
}

// :title=@types/next-auth.d.ts

import { AppSessionUser, AppToken } from './types';

declare module 'next-auth' {
  /** Returned by `useSession`, `getSession`, and `getServerSession` */
  interface Session {
    user: AppSessionUser;
    tokens?: AppToken;
  }

  interface User {
    /** Only present when using credentials provider */
    tokens?: AppToken;
  }
}

declare module 'next-auth/jwt' {
  interface JWT {
    tokens?: AppToken;
  }
}

Back to our options.ts file. We are going to define some utility functions and an enum of supported providers.

// :title=options.ts

export enum AccountProviderEnum {
  GOOGLE = 'google',
  APPLE = 'apple',
}

export const never = (_: never) => {
  throw new Error('Unimplemented')
}

export const getAuthorization = (token: AppToken | null) =>
  token ? `${token.type} ${token.access_token}` : undefined

We should define our credentials provider handler used in the authorize method. This function authenticates a user using their email, and password credentials, and uses the resulting token to get the user’s identity by calling another function with it that returns the user account object. A subset of the data from the user account object is returned from this function:

// :title=options.ts

const authorizeHandler = async (credentials: SignInCredentials, _req: any) => {
  const { data: token } = await authenticateAccountService(credentials)
  const { data: identity } = await identifyUserAccountService({
    headers: { Authorization: getAuthorization(token) },
  })

  const account = identity.data

  // The returned value here becomes the user object in the `jwt` callback args (`params.user`)
  // The `id` in this returned object is used to add a `sub` property to token (`params.token`)
  return {
    id: account.id,
    email: account.email,
    name: account.user.fullname,
    image: account.avatar,
    tokens: token,
  }
}

Next is our jwt callback, which gets called after a successful round trip—a two-way redirect to and from the OAuth provider—or after our authorize function in the credentials provider returns. We’ll further split this jwt callback into a couple independent functions. We are handling just two things, or more technically “triggers”, in our jwt callback: the "signIn" trigger and the "update" trigger. Our signIn trigger handles three things, which are the "credentials", "google", and "apple" providers, but I’ll only be talking about the "credentials" and "google" providers.

// :title=options.ts

type JWTCallback = NonNullable<AuthOptions['callbacks']>['jwt'];
type Params = Parameters<JWTCallback>[0];
type Account = Params['account'];

const googleHandler = async (account: Account, jwt: JWT, intent: AuthIntent) => {
  let identity: UserAccountResponse | undefined = undefined;

  if (!account.access_token || !account.id_token) {
    throw new Error(`Access token and ID token are missing in the ${provider} provider`);
  }

  // You'll send this to your API where you verify the tokens, and get the user info
  // to register them with, from Google's tokeninfo endpoint
  const credentials = {
    access_token: account.access_token,
    id_token: account.id_token,
    provider: AccountProviderEnum.GOOGLE,
  };

  // The intent passed to this factory function as received from the request cookies
  switch (intent) {
    case 'signin':
      break; // noop
    case 'signup':
      ({ data: identity } = await createAccountOIDCService(credentials));
      break;
    default:
      never(intent);
  }

  // After registration we'll still authenticate (signin) anyway.
  // So "signin" case above is a no-op
  const res = await authenticateAccountOIDCService(credentials)
  const token = res.data

  // identity will be undefined for intent="signin" but will
  // be of type UserAccountResponse if "signup"
  if (!identity) {
    ({ data: identity } = await identifyUserAccountService({
      headers: { Authorization: getAuthorization(token) },
    }));
  }

  // Make sure you update the `sub` property of the token (jwt is params.token)
  // to use the ID given to the user by your application rather than the provider
  // account ID which is the user's Google account ID in this case
  return { ...jwt, tokens: token, sub: identity.data.user.id };
};

Since, I believe, our OAuth scope for Google is user.profile user.email openid, we get both an access_token and an id_token. We send these tokens with the name of the provider that granted them (google) to our backend where the tokens are verified and the user information is retrieved using Google’s tokeninfo endpoint in this case.

Make sure to check the aud field of both the access and id tokens. Check that it matches your GOOGLE_ID (GOOGLE_CLIENT_ID).

When the intent we retrieved from the request cookies is signup, we create an account for the user using their credentials. Notice that in the case of signin it’s a no-op, because whatever applies to the signin case here also applies to the signup case, and we don’t want to repeat ourself, so we just wait to do it after the switch-case statement—we authenticate the user either ways to get their session tokens and add these tokens to the returned object, which is further used down the callbacks pipeline in making the eventual NextAuth.js session and also serialized to make the NextAuth.js JWT token, since we are not using a database strategy.

Make sure to override the existing sub field in the params.token from the original callback which is passed into our function as jwt with the user ID generated by your application as the default is the user’s Google account ID.

// :title=options.ts

const signInTrigger = async (params: Params, jwt: JWT, intent: AuthIntent) => {
  const account = params.account!; // account is available when the trigger is "signIn"
  const provider = account.provider as BuiltInProviderType;
  const user = params.user; // user is available when the trigger is "signIn"

  switch (provider) {
    case 'credentials': {
      // The application-provided token returned from the authorize method in the credentials provider
      return { ...jwt, tokens: user.tokens };
    }
    case 'google': {
      return await googleHandler(account, jwt, intent);
    }
    default:
      // Our app only supports Google and Apple, although I'm skipping "apple" here
      never(provider as never)
      return jwt; // unreachable but typescript won't know
  }
}

The signInTrigger function is simple enough. Switch between providers for as many as are supported. The return statement in the default case is not necessary since never throws an error, but TypeScript can’t see that. The return statement prevents our return signature from being unioned with undefined

Whew, finally we arrive at our getAuthOptions function! We will go ahead now and define our getAuthOptions factory function.

// :title=options.ts

export const getAuthOptions: (intent: AuthIntent) => AuthOptions = (intent) => {
  return {
    pages: { signIn: Routes.SIGNIN, newUser: Routes.HOME },
    providers: [
      GoogleProvider({ clientId: GOOGLE_ID, clientSecret: GOOGLE_SECRET }),
      CredentialsProvider({
        credentials: {
          email: { label: 'Email address', type: 'email' },
          password: { label: 'Password', type: 'Password' },
        },
        async authorize(credentials: SignInCredentials | undefined, req) {
          if (!credentials) return null;
          return await authorizeHandler(credentials, req)
        },
      }),
    ],
    callbacks: {
      async jwt(params) {
        const jwt = params.token;
        if (params.trigger === 'signIn') {
          Object.assign(jwt, await signInTrigger(params, jwt, intent));
        } else if (params.trigger === 'update') {
          // TODO: validate params.session
          const update: Session = params.session;

          // When you update your session by refreshing your application tokens, for example.
          Object.assign<JWT, JWT>(jwt, {
            tokens: update.tokens,
            email: update.user.email,
            name: update.user.name,
            picture: update.user.image,
            sub: update.user.id,
          });
        }
      },
      session(params) {
        // We've made mutations to params.token in the `jwt` callback
        // We can access those mutated fields here and compose them to make our session object.
        params.session.user.id = params.token.sub;
        params.session.tokens = params.token.tokens;

        // This is the eventual session object we get when using `useSession` or `getServerSession`
        return params.session;
      },
    },
  };
};

No more explaining. Go figure!

Ah, meh, that was a long one! Sh*t got too real that I forgot to make even more jokes. But can’t lie the hat-trick joke was too good. Then following it with that GIF where the third Spider-Man dropped in just to talk about the third attempt at a solution that does the trick. The third time is, really, always the charm.

Dot Notation Type Accessor in TypeScript

Caleb Adepitan — Mon, 26 Dec 2022 17:20:51 +0000

I was randomly scrolling Twitter and came across this—

Hmm, ¿son un tío o una mujer? No sé.

But anyway their name was trash, and yeah I mean "trash". Okay, I just did some digging on their profile and his real name is
Chris Bautista, you can hear him say "I'm trash" like "I am Groot".

Back to what I was saying—I don't know what it is with me and not keeping to topic. I just want to say so many things in so little
time, and it's killing me, argh!

Yeah, back to what I was saying, for real: @trashh_dev wrote this tweet about someone making react i18n type-safe. From the
moment I saw "made react i18n type safe", I was intrigued, like, "how did they do that?". I saw the code snippet following and I thought
to try it out. Brethren, lo and behold, it was legit.

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

The code snippet was easy to understand, but I never knew TypeScript could infer string literals. I guess that was my #TIL for
the day.

So after seeing that, I thought about another use case. One that has always been common with me—accessing property types from a parent
type or interface.

interface User {
  name: string
  nick: string
  dateOfBirth: Date
  address: {
    city: string
    state: string
    country: string
    zip: string
  }
}

So given this User type, say I need just the address type, this is what I'll do in TypeScript.

const address: User['address'] = {
  city: 'Ikeja',
  state: 'Lagos',
  country: 'Nigeria',
  zip: '100001',
}

This is fine! But it starts looking not so fine when the type gets deeper.

interface User {
  name: string
  nick: string
  dateOfBirth: Date
  address: {
    city: string
    state: string
    country: string
    zip: string
    coords: {
      lat: number
      lng: number
    }
  }
}

Now, we only just need coords so let's pluck it:

const coordinates: User['address']['coords'] = { lat: 7.152627, lng: 3.657474 }

You may be thinking:

Why would anyone have to do this?
Why not just make an Address type and a Coordinates type?

Plus one for being a critical thinker.

Let's try to tinker since we've got a thinker amongst us:

interface Coordinates {
  lat: number
  lng: number
}

interface Address {
  city: string
  state: string
  country: string
  zip: string
  coords: Coordinates
}

interface User {
  name: string
  nick: string
  dateOfBirth: Date
  address: Address
}

And then we can do better:

const coordinates: Coordinates = { lat: 7.152627, lng: 3.657474 }

const address: Address = {
  city: 'Ikeja',
  state: 'Lagos',
  country: 'Nigeria',
  zip: '100001',
  coords: coordinates,
}

But trust me, not every value is made of a type—some types are made of a value—because you may never know the type till after the value
has been created (or composed). Thank goodness an example isn't far from us and I didn't even write it.

Take a look at the code snippet in the image tweeted by trash embedded above: the type of Translations isn't known until after the
value of translations has been composed. Some other times this same pattern may be adopted to avoid duplication. When the type and the
value would eventually end up being the same, then we can just infer the type from the value using a typeof (TypeScript) operator.

const translations = {
  translationOne: 'hello world',
  translationTwo: 'hello {{world}}',
  translationThree: "hello {{world}}, I'm {{name}}!",
  translationFour: '{{foo}} has a {{bar}}',
} as const

type Translations = typeof translations

The value of translations above isn't made of a type, whereas the type of Translations is made of a value.

Few reasons why this may be the case:

To avoid duplication, types are inferred from object values using the (TypeScript) typeof operator.
Sometimes the values are known before the types because it's the value that makes the type.
Some libraries may not export all the types contained in a parent type (i.e these child types are kept private to the library and only just exist on their parent interface or type)

How I plan to make this better

So just like lodash where you can access object properties using the dot notation, we'll create a Choose type
that can help us choose the type of child properties from a parent type.

Unlike in lodash, accessing array or tuple types with
bracket–index notation is not accounted for.

export type Choose<
  T extends Record<string | number, any>,
  K extends string
> = K extends `${infer U}.${infer Rest}` ? Choose<T[U], Rest> : T[K]

This is just like a normal recursive function:

Infer the first string literal that appears before a dot as a type U.
Pack subsequent string literals appearing after a dot into a type Rest.
So long as type K has a dot within it, keep calling this type on type T[U] while passing Rest as the new type of K.
Otherwise, terminate at the point where K has no more dots and return the type T[K]

Note that this would break if the object key(s) contains a
dot which is our chosen delimiter.

const coordinates: Choose<User, 'address.coords'> = {
  lat: 7.152627,
  lng: 3.657474,
}

const address: Choose<User, 'address'> = {
  city: 'Ikeja',
  state: 'Lagos',
  country: 'Nigeria',
  zip: '100001',
  coords: coordinates,
}

The only shortcoming of this known to me is that we can't get static type inference on the second parameter of Choose which would be
the dot-notated keys of the type T, in this case, User.

There are ways to fix this, but not so reliant, because it's a recursive computation too, and type T can be just any type such that we
can't tell how deep it gets. TypeScript starts complaining after certain levels of recursive computing.

type Join<K extends string | number, P extends string | number> = `${K}.${P}`

export type DeepProps<
  T extends Record<string | number, any>,
  K extends Exclude<keyof T, symbol> = Exclude<keyof T, symbol>,
  U extends string | number = ''
> = T[K] extends Record<string | number, unknown>
  ?
      | (U extends '' ? K : U)
      | DeepProps<
          T[K],
          Exclude<keyof T[K], symbol>,
          U extends ''
            ? Join<K, Exclude<keyof T[K], symbol>>
            : U | Join<U, Exclude<keyof T[K], symbol>>
        >
  : U

If you want me to explain what's going on here, it may take me writing another post or maybe not. Not that it's difficult, but I currently
can't think of a way to explain it that'll be concise enough. All I can say is, if you care enough, copy it, break it and reconstruct the
logic bottom up, one step at a time, and see how the logic composes to achieve the desired result.

Alright, alright, I've heard you! Here you go:

We have a Join<K, P> type that concats two string literal types K and P delimiting them with a dot.
A DeepProps<T> type that enumerates all the paths in a type or an interface.
DeepProps<T> has internal args K and U, where K is the keyof T with symbol excluded and U is the eventually joined paths carried from one call of DeepProps<T, K, U> to another.
If U is currently '', i.e no paths have been joined, union K which is the keyof the current type T with a call to DeepProps<T[K], keyof T[K], ...>.
U is carried to the next call of DeepProps so it can be further union'd with each successive call till a base case is hit where only U is returned.

If you are familiar with recursive functions from normal day-to-day programming this will be easy to comprehend. All the patterns used are
similar to those used with recursive routines.

type Keys = DeepProps<{
  app: { game: { lame: number; blame: string; same: { came: string } } }
}>

// type Keys = "app" | "app.game" | "app.game.lame" | "app.game.blame" | "app.game.same"

Notice that "app.game.same.came" isn't present in the permutations. For whatever reason, it goes as deep as is common to all keys at a
certain level.

export type Choose<
  T extends Record<string | number, any>,
  K extends DeepProps<T>
> = K extends `${infer U}.${infer Rest}` ? Choose<T[U], Rest> : T[K]

Now, you get type inference on the second parameter K which is a permutation of the keys in object T strung together with a dot
wherever necessary

If you used this type on another object, TypeScript might choke on it, so it's just safe to not use it at all.

After all considerations, our eventual type is this:

export type Choose<
  T extends Record<string | number, any>,
  K extends string
> = K extends `${infer U}.${infer Rest}` ? Choose<T[U], Rest> : T[K]

and TypeScript won't choke along the way!

Creating Stacked Image Swap Animation

Caleb Adepitan — Sat, 26 Nov 2022 09:24:02 +0000

Hello folks!

It's been quite a while, and would be pretty rude of me to get into anything without at least saying hello.
I can't really tell what the reason is, why I've been writing a little less often. Hmm—"a little less often"—that's an
understatement!

So what it is really is, I've been playing my hands 'round a couple of stuff and just thought to share one simple yet
interesting part of the things I fiddled with earlier this past week.

I had to sprinkle some images here and there while developing a landing page to help the company I work with hit marketing goals.
It was a quick detour from my major tasks (I'll explain later...not exactly, I'll explain now).

Nice job the designer did, really! So they struck a deal with me to help breathe some life into their work of art.
Everyone wants to see their products alive and well, everyone, especially product designers, haha! So I took the deal, and guess what I was to get in return, argh, it's so ridiculous—a stick sweet! Well not one, but two every day till the deal is done.

The original deal was four everyday, but they said they were concerned about my health, now that's not a bad thing, so two
it was.

Time to stack these images

I implemented this design bottom-up after developing the basic layout structure, things like, header and footer, etc. Although, I
had no reason why I wanted to take it bottom up, or maybe I did, maybe I knew I had something special for the hero section which
was at the top, immediately after the header, so I saved the best for the last. Thing is, the design never specified how these
images should animate, so I conjured one from the deep of my mind, some kind of Leonardo Da vinci's shit, yunno.

When there's incentive there's motive

Oh, they actually do mean the same thing!

Well, what I meant to mean by that was: incentives motivate people; but I think you already know that, right?
I didn't do it for the sweet, but because it was fun that I thought I was doing it for the sweets. Oh, seven heavens! I've
completely lost track of time. Okay, okay, okey, now that I'm motivated, let's get into it yuh!

What we need

First, we need a couple images to make this work. We can go cop some from Unsplash. Thereafter, we create
a normal JavaScript/React project and install a couple dependencies to make it work, but I trust you know how to make that work
so I won't get into that.

yarn add @chakra-ui/react @emotion/react @emotion/styled @emotion/memoize framer-motion react react-dom

# etc etc

Yeah, we'll use chakra, because I don't know how to create CSS files anymore and I just like to write everything inside the component.

Setting up our app

While working on this really, I worked on a Next.js framework, but here I'll try to be as framework agnostic as I can be. We
start by creating our app file, doing a couple imports as neccessary and writing some JSX or TSX. We go ahead to create our index
file and import our app file inside it rendering into the node#root in the index.html file.

import { ChakraProvider } from "@chakra-ui/react";
import { StackedImageAnimation } from './StackedImageAnimation';

const App = () => {
  return (
    <ChakraProvider>
      <StackedImageAnimation>
    </ChakraProvider>
  );
};

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

import App from "./App";

const rootElement = document.getElementById("root");
const root = createRoot(rootElement);

root.render(
  <StrictMode>
    <App />
  </StrictMode>
);

Now to the main file that really concerns us, asides these boilerplates. We create our StakedImageAnimation.tsx file and get it
started.

import { Box } from "@chakra-ui/react";

export const StackedImageAnimation = () => {
  return (
    <Box>
      <Box></Box>
    </Box>
  );
};

Collecting assets

We'll now head to Unsplash and get some images, about four of them at least. You don't need to download the
images, you can just copy their respective resource links as I did in the code below.

const images = [
  'https://images.unsplash.com/photo-1576398289164-c48dc021b4e1?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80',
  'https://images.unsplash.com/photo-1499028344343-cd173ffc68a9?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80',
  'https://images.unsplash.com/photo-1524593166156-312f362cada0?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80',
  'https://images.unsplash.com/photo-1506917728037-b6af01a7d403?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80',
]

Now, what we want to do is render these images inside our component. You could render them either by using an <img /> tag
(using chakra's <Image /> component) or just render them in a <div /> as a background image (using chakra's <Box />). I
personally prefer to render them in a div leveraging CSS background-image and related properties.

import { Box } from "@chakra-ui/react";

const images = [
  "https://images.unsplash.com/photo-1576398289164-c48dc021b4e1?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80",
  "https://images.unsplash.com/photo-1499028344343-cd173ffc68a9?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
  "https://images.unsplash.com/photo-1524593166156-312f362cada0?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
  "https://images.unsplash.com/photo-1506917728037-b6af01a7d403?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80"
];

export const StackedImageAnimation = () => {
  return (
    <Box>
      {images.map((image, i) => {
        return (
          <Box
            key={image}
            backgroundImage={`url(${image})`}
            backgroundSize="cover"
            backgroundRepeat="no-repeat"
          />
        );
      })}
    </Box>
  );
};

If you're quite familiar with this, at this point we are in the code, you should know you won't see any image rendered. The boxes
are there rendered as regular divs in the DOM, but they're empty, and as a result have no definite height or width. If height and
width aren't explicitly set on an element, then they default to "auto" for the browser to calculate itself based on what's
contained inside the element.

What we'll do now is set height and width on the containing box, that is the one that wraps the inner boxes and let our inner
boxes inherit their dimensions from this parent box.

Another thing is, we need to take these elements out of the regular layout flow, because even the idea of stacking them atop each
other suggests so. To do this, we give each of the rendered image an absolute position, which helps to position them relative to
their closest relative-positioned ancestor.

export const StackedImageAnimation = () => {
  return (
    <Box>
     <Box width={580} height={450} position="relative">
      {images.map((image, i) => {
        return (
          <Box
            key={image}
            backgroundImage={`url(${image})`}
            backgroundSize="cover"
            backgroundRepeat="no-repeat"
            width="inherit"
            height="inherit"
            position="absolute"
            top={0}
            right={0}
          />
        );
      })}
    </Box>
  );
};

The images are stacked now, but no, they aren't visually stacked yet. To achieve that visual effect, we need to find a
way to shrink down images in the rear and offset them to the right, each successive one farther than the one before it, all in
the same geometric progression. This gives that perspective effect thereby making the images look stacked.

Understanding the animation flow

Before we can fully understand how the stacking will be achieved, we also need to understand how the swapping will happen. They
are both intertwined.

How could we forget about z-index when talking about stacking. To control how these images are stacked we need to manage their
respective z-indices at every point in the animation. But z-index isn't the only index we need to control, we also need to
control the active index of the stack. The active index tells us which of these images has just moved to the front of the stack.
We manage the active index—just like a fuel pump counter—using a circular roving technique, making use of modular arithmethic (%).

By moving just one of these images from their current position P to Q, their respective z-indices is recomputed. This happens
when the active index changes, say we have four images, the lower limit is 0 the upper limit is 3. We must make sure that
when the upper limit is reached, it doesn't tend towards infinity, but returns to its lower limit to start all over again, on and
on in a circular roving manner, rotating from 0 to 3 to 0. The mathematical formula to make sure of this is:

(activeIndex + 1) % len(images)

(a + 1) % l = n

where `a` is active index;
      `1` is a constant;
      `l` is the length of images list;
      `n` is next active index

(0 + 1) % 4 = 1 <--
(1 + 1) % 4 = 2   |
(2 + 1) % 4 = 3   |
(3 + 1) % 4 = 0 <--

Now that we know how to manage our active index let's go ahead and add that to the code. Our active index only changes every five
seconds, and we manage that using a setInterval inside a useEffect hook.

import { useEffect, useMemo, useRef, useState } from 'react';

export const StackedImageAnimation = () => {
  const [activeIndex, setActiveIndex] = useState(0);
  const timer = useRef<NodeJS.Timeout | number>(-1);
  const size = useMemo(() => images.length, []);

  useEffect(() => {
    timer.current = setInterval(
      () => setActiveIndex((cur) => (cur + 1) % size),
      5000
    );

    return () => clearInterval(timer.current as number);
  }, [size]);

  return (...);
};

As observed in the figure above, we could map indices to z-indices, and notice that the z-indices aren't changing, it's only the
active indices that keep rotating. When the rotation occurs the index at the top of the stack (active index) assumes or inherits
the z-index at that position in the map for as long as the active index hasn't changed (in our case for 5000 milliseconds).

The codeblock that follows is an implementation of the above image which specifies how the active index rotates around the z-index

const map = useMemo(() => {
  const map = new Map<number, number>()
  const len = images.length
  let i = len

  if (len < activeIndex || activeIndex < 0)
    throw new Error('Invalid index set as active index')

  while (i > 0) {
    // highlight-next-line
    map.set((activeIndex + len - i) % len, --i)
  }

  return map
}, [activeIndex])

Now this map here, which computes every single time our activeIndex changes (every 5000 milliseconds) is the solution to most
of our problems.

Hopefully, the part that throws an exception would never be reached as long as all goes as planned. So it's redundant, except
that it communicates intent to whoever is reading it, as to what would be an unexpected behaviour for our program.

It could be quite difficult to make sense of the line of code inside the while
loop. It's as good as saying (activeIndex + i) % len if
i had started from 0 and not the length of the
images list 4. So when i = 4; len - i = 0, and since
i keeps decreasing every step of the loop, it would just
seem like i increases from 0-3

Shrinking and offsetting rear images progressively

Now that we've established the framework for our animation, majority of what seemed difficult to do are by a great deal easier now.
One way I can think of for shrinking down rear images is to transform them using the CSS scale function. For offseting, there
are two possible ways I can think of: one of which is also to transform using CSS translate function; two, is to make use of the
CSS right property since our images are absolute-positioned to their relative-positioned parent box.

Now, some other deductions we can make is that the scale and the offset are a function of the z-index. Since the image with the
highest z-index (top of the stack) needs no shrinking and offsetting, and the image with the least z-index (bottom of the stack)
needs the most shrinking and offsetting.

The dependent variables here are the scale and offset factor, while the independent variable is the z-index which we can always
retrieve from the map for each index of the images.

We can pick a constant, multiple of which will make the cumulative factor by which our images would be scaled down and offset.
I prefer to pick something small, say 0.075 or 0.09 maybe.

<Box width={580} height={450} position="relative">
  {images.map((image, i) => {
    const factor = size - 1 - map.get(i)!;

    return (
      <Box
        key={image}
        backgroundImage={`url(${image})`}
        backgroundSize="cover"
        backgroundRepeat="no-repeat"
        width="inherit"
        height="inherit"
        position="absolute"
        top={0}
        right={0}
        right={0 - 0.075 * factor * 580}
        transform={`scale(${1 - 0.075 * factor})`}
      />
    )
  })}
</Box>

size - 1 in the code above, when computing our factor is
just a reminder that our indices goes from 0-3
but length of our list goes from 1-4

What goes into factor?

So this is the deal: take a look at the figure image that lays out the active index to z-index mapping. Say our active index is
2 and i is also currently 2, then to find the appropraite z-index for images[2], we'll do a map.get(i) value of which
should be 3. Every time our active index changes, all indices are re-rotated around the z-index. As I said earlier, the scale
and offset are a function of the z-index. images[2] is at the top of the stack, so it needs the least shrinking and offsetting;
images[1] is at the bottom of the stack, so it needs the most shrinking and offsetting. In other words, scale and offset are
inversely related to the z-index. At active index 2 the z-index is up to 3; to get the correct factor we do a
size - 1 - map.get(i), where size = 4, giving a final result of 0.

When i was at 1, map.get(i) gives a z-index of 0. Running that through our function again, size - 1 - map.get(i) will
give 3.

We take this computed factor and multiply with our base diminishing factor of 0.075 to get multiples of it progressively down
the loop.

Where does `580` come from?

scale acts on the size of an object (x, y) or (width, height). If we'll be calculating the offset across the x-axis (right), then we must know what proportion of the initial size (width) of our object (in this case element) it was diminished by. We take out that same proportion to the right to make up for the shrink in the offset. There and there we have it, our images looking stacked.

Where do we go from here?

Now that we have our images stacked and swapping every five seconds we rotate the active index in our useEffect hook, we need to make this animation feel more natural. Some transitioning would do the trick actually, and we can go ahead and achieve that using the CSS transition property.

Something that we are forgetting, and you have failed to remind me is setting our z-index.

<Box width={580} height={450} position="relative">
  {images.map((image, i) => {
    const factor = size - 1 - map.get(i)!;
    const isPreviousActiveIndex = (activeIndex + size - 1) % size === i;

    return (
      <Box
        key={image}
        backgroundImage={`url(${image})`}
        backgroundSize="cover"
        backgroundRepeat="no-repeat"
        width="inherit"
        height="inherit"
        position="absolute"
        top={0}
        right={0 - 0.075 * factor * 580}
        transform={`scale(${1 - 0.075 * factor})`}
        zIndex={map.get(i)}
        transition={"z-index 0.6s ease, transform 0.6s ease".concat(
            isPreviousActiveIndex ? ", right 0.3s ease" : ""
        )}
      />
    )
  })}
</Box>

Hmm...I thought we only mentioned z-index and transition.
Why are we doing a isPreviousActiveIndex check?

Good question!

We want a right transition only for the image that was formerly at the top of the stack which is now getting swapped out to the
bottom just for the one right behind it to come to the top. The others don't need that right transition, they will just grow bigger and move quite inwards from the right. What really matters is how they grow bigger, but for the one moving to the bottom, it starts with moving outwards to the right and then growing smaller so we want both transitions for it.

Putting the pieces together

import { Box } from "@chakra-ui/react";
import { useEffect, useMemo, useRef, useState } from 'react';

const images = [
  "https://images.unsplash.com/photo-1576398289164-c48dc021b4e1?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80",
  "https://images.unsplash.com/photo-1499028344343-cd173ffc68a9?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
  "https://images.unsplash.com/photo-1524593166156-312f362cada0?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2370&q=80",
  "https://images.unsplash.com/photo-1506917728037-b6af01a7d403?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=2148&q=80"
];

export const StackedImageAnimation = () => {
  const [activeIndex, setActiveIndex] = useState(0);
  const timer = useRef<NodeJS.Timeout | number>(-1);
  const size = useMemo(() => images.length, []);

  useEffect(() => {
    timer.current = setInterval(
      () => setActiveIndex((cur) => (cur + 1) % size),
      5000
    );

    return () => clearInterval(timer.current as number);
  }, [size]);

  const map = useMemo(() => {
    const map = new Map<number, number>();
    const len = images.length;
    let i = len;

    if (len < activeIndex || activeIndex < 0)
      throw new Error('Invalid index set as active index');

    while (i > 0) {
      map.set((activeIndex + len - i) % len, --i);
    }

    return map;
  }, [activeIndex]);

  return (
    <Box width={580} height={450} position="relative">
      {images.map((image, i) => {
        const factor = size - 1 - map.get(i)!;
        const isPreviousActiveIndex = (activeIndex + size - 1) % size === i;

        return (
          <Box
            key={image}
            backgroundImage={`url(${image})`}
            backgroundSize="cover"
            backgroundRepeat="no-repeat"
            width="inherit"
            height="inherit"
            position="absolute"
            top={0}
            right={0 - 0.075 * factor * 580}
            transform={`scale(${1 - 0.075 * factor})`}
            zIndex={map.get(i)}
            transition={"z-index 0.6s ease, transform 0.6s ease".concat(
                isPreviousActiveIndex ? ", right 0.3s ease" : ""
            )}
          />
        );
      })}
    </Box>
  );
};

Don't forget we have the codesandbox above there for you to take a look and fiddle with as you think is interesting.

Don't forget to share also!

Thank you and have a wonderful week!

The Magic of Using TypeScript at Runtime

Caleb Adepitan — Thu, 24 Dec 2020 06:36:15 +0000

Ever wanted to pass the path to a TypeScript file to some other library or module maybe to run it in a separate process or in a worker thread.
You think you can just write the file in JavaScript, but you found out you will need to import another one or two of your TypeScript files beacuse it needs a function from it. Then I guess you have to refactor your whole codebase to use JavaScript instead, or not, if you read through this.

The problem is, using require with a TypeScript file won't work, because Node.js does not and cannot handle .ts files. The extensions handled by the require function by default are .js, .mjs, .node, .json. The libaray or module you are passing the file path to would eventually require it at runtime and even if you add .ts to require.extensions, it would only resolve properly, but you get a syntax error on execution. This means sending it a TypeScript .ts file won't work, require will choke on this.

import { Worker } from 'worker_threads'

const worker = new Worker('./path/to/typescript/worker.ts')

At runtime in the worker_threads module it would probably look somewhat like this

class Worker {
  constructor(filename) {
    const mod = require(filename)
  }
}

Well, the implementation is quite different, but my point is; filename will eventually go through require maybe not in this same process.

The magic

The only option is to precompile your TypeScript files, know where the compiled file would be output to before it would be compiled, then pass it the path. But what if you use a runtime like ts-node, which compiles on the fly and run the compiled files in-memory without emitting? There's no way to do this, except:

File 1: `worker.js`

A base JavaScript file to portal every worker file written in TypeScript to.

// worker.js
const { workerData } = require('worker_threads')

require('ts-node').register()
require(workerData.aliasModule)

File 2: `worker.ts`

The module containing the code to be run on a worker thread, which is actually written in TypeScript.

// worker.ts
const { parentPort, workerData } = require('worker_threads')

parentPort.postMessage(`Post back: ${workerData.whatever}`)

File 3: `index.ts`

This is the main file that needs to run a job on a worker thread. It begins the whole worker thread thing.

// index.ts
import path from 'path'
import { Worker } from 'worker_threads'

const worker = new Worker('./worker.js', {
  workerData: {
    aliasModule: path.resolve(__dirname, 'worker.ts'),
    whatever: 'Hello, worker bee! The Queen greets you.',
  },
})

worker.on('message', (message: string) => {
  console.log(message) // Post back: Hello, worker bee! The Queen greets you.
})

If you are setting a timeout to terminate the worker so you don't wait for too long when it hangs, bear in mind the worker may take quite long to post a message, because it will first do some TypeScript compilation and type-checking. You could make it fatser by setting transpileOnly option to true on register.

Most of the magic is done by ts-node using the require('ts-node').register() which registers the loader for future requires. The most beautiful thing about this magic is that you can dynamically set the module to load, because of the way the modules are structured. Therefore uisng worker.js for future workers but running different code in it is possible.

Re-creating the magic with a job queue like Bull

If you ever used a job queue in a Node.js application or more specifically, Bull, you will know you sometimes have to run a job in a different process (child process) from the main one (parent process). Bull lets you specify the path to the file or filename that conatins the code to process the job. Whenever you pass a file to queue.process, Bull knows to process that job in a different process.

In the case where a job processor is CPU intensive, it could stall the Node.js event loop and this could lead to double processing a job. Processing jobs on a separate process could prevent double processing it. Processing the job on a separate process would also make sure the main process doesn't terminate even when the job process terminates maybe due to a runtime error.

The same problem as with worker threads happens here again if we are using TypeScript. We can't do:

queue.process('./path/to/typescript/process-job.ts')

As we did with the worker thread example, although may not be as dynamic as that, we could do the same here also.

We create the queue and add a job to be processed to it. We then specify the code file that processes the job off of the queue.
Bull will run this code file in a separate process, but it can't handle TypeScript files.

// index.ts
import Bull from 'bull'

const queue = new Bull<IData>('job-queue', options)

queue.add('job-name', data)

queue.process('job-name', './path/to/processor.js')

Using the ts-node register method as before, we register a loader to be used for future require, then load the TypeScript code file, compile it and run it. Bull picks the top level export (default export or unnamed export) from module.exports and invokes it with the job object containing info sepcific to the job and the data, sent from queue.add, to be processed.

// processor.js
require('ts-node').register()
require('./processor.ts')

The processor.ts file is the file containing the original code to process the job.

// processor.ts
export default async function (job: Bull.Job<IData>) {
  // do something with job.data
}

Understanding the Event Loop and I/O Operations

Caleb Adepitan — Thu, 15 Oct 2020 11:56:21 +0000

The event loop is a design pattern in computer science. The pattern is as simple as waiting for an event and dispatching an event so services that can handle the event consume it. The the loop blocks till another event is inbound for processing.

Your Node.js Express server for example, would not exit its process. At that point, it waits for an event (a request). When the event arrives, the event is emitted and picked up by the GET handler in your router for that specific request. This is just on the high level. The moment the event loop stops, i.e the loop breaks, the Node.js process exits and as a sequel, your Express server too.

Ending the Node.js process itself is an event. By hitting
Ctrl + C you agree to send a SIGINT (interrupt)
signal that terminates the process.

I/O, or simply put, Input/Output, on the other hand, is what makes a computer a computer. A machine incapable of input and output cannot be called a computer. Computers are meant to take instruction, do something with it, and give a result. Do you see any possible way to do that without I/O?

The request sent over HTTP to your Express server is the input and the response to the request is the output.

See! The pieces are coming together.

The Ctrl + C you hit everytime you want a process terminated is
input and the termination itself or a "...(Y/N)?" question you get is a
response to the input — an output.

Blocking I/O and non-blocking I/O

In blocking I/O, the function that creates an I/O request blocks further execution in the thread till the request completes. The time it takes for any request to complete can vary from few milliseconds to even as long as the user doesn't supply an input. An example of blocking I/O when reading from the console:

const prompt = require('prompt-sync')({ sigint: true })

// Blocking I/O request
const name = prompt('Enter your name: ')

console.log(`Welcome ${name}, king of the seven kingdoms`)

If the user at the end of the console takes, say, two minutes to type their name and hit the carriage return. The thread blocks for two minutes and when the return key is hit, execution continues and the welcome message is logged.

In the non-blocking I/O mechanism, a request to either read or write to an operating system's resource immediately returns without actually waiting for the read or write operation to complete. A predefined constant according to the OS is returned which relays the state of the operation to the executing program.

const fs = require('fs')

const code = 'console.log("Smart code")'

// Non-blocking I/O request.
fs.writeFile('/path/to/some/file.js', code, err => {
  if (err) {
    console.error(err)
    return
  }
  console.log('Successfully wrote a code file!')
})

Understanding boundaries between synchrony and asynchrony

A source of confusion for me in earlier times was the word synchronous and asynchronous. The first time I was introduced to really knowing what these words meant was when I started working with XMLHttpRequest in JavaScript. But I didn't "really know" what they meant. I could have checked my dictionary again and again, but trust me I knew what they meant literally.

Synchrony is the normal flow in your code where every command or line of code continues to execute almost at the same instant, simultaneously. Asynchrony as opposed to synchrony is when the execution of one command or line of code takes longer to complete or doesn't complete until a specific thing happens and as such could block further execution of following commands or lines.

Synchronous and asynchronous programming

Asynchronous procedure calls normally, are calls to access a blocking resource. If these calls were to be handled synchronously, they would block the thread they are run on. In order to prevent these calls from blocking a thread, many programming languages adopt some constructs called Future and Promises. (Promises should sound familiar, you may know Future from Java). Once a thread is blocked by an operation, further program execution on the thread suspends and is only returned control when the operation completes.

const fs = require('fs')

// Reading a file in a blocking manner.
const file = fs.readFileSync('/path/to/file.js')

// This will never log till the file is ready
console.log('Doing something else...')

To prevent an operation that takes long to complete from blocking a thread, there has to be a way to handle them differently from synchronous operations. When handled differently from synchronous operations, then the event loop can keep processing other events in the queue while it waits for the undeterministic operation to complete. That is, the execution of this operation can be left in a partial state (the result of the operation cannot be determined yet) and when the result can be determined, if there are currently no events in the queue to be processed by the event loop, it can return to complete the operation immediately.

JavaScript is single threaded therefore the only way it can handle asynchronous operations in a non-blocking manner is to have some level of concurrency built in. Multi-threaded languages like Python and Java can easily allow you to create a new thread to run asynchronous operations on, but not with JavaScript. With JavaScript, it's either a callback or a promise.

Synchronous event demultiplexer

The synchronous event demultiplexer or event notification interface as part of most modern operating systems is a native mechanism to effciently handle concurrent non-blocking resources. Rather than using polling algorithms like the busy waiting technique, which is often a waste of CPU cycles, the operating system provides an event demultiplexer interface.

Linux epoll
Mac kqueue
Windows I/O Completion Port IOCP

const fs = require('fs')

// While this resource is not ready for read
// The Event demultiplexer associates the resource with a read operation
// When the resource is ready and can be read
// The Event demultiplexer pushes a new event to the
// event queue to be processed by the event loop
// This callback is the associated handler for the event
fs.readFile('/path/to/some/file.js', (err, data) => {
  if (!err) {
    // do something with data
  }
})

// This would log before you do something with data
console.log('Doing something else...')

The event demultiplexer takes some resources and calls watch() on them for specific operations, like a read() operation. The call to watch() on the resources is a blocking synchronous call. After a read request on the resources has completed, watch returns some new events and the event demultiplexer pushes these new events to the event queue and control is returned to the event loop since the synchronous blocking call to watch has returned. The event loop processes each event from the event queue and the associated handler for each event is invoked. The event loop gives control to an handler because it trusts it to be non-blocking and in some few milliseconds the handler will return back the control to the event loop (stuff can sometimes go south). The handler can also cause new resources to be added to the event demultiplexer for watch, after which it returns control to the event loop. If there are remaining events in the event queue, the event loop processes these events also as it did with prior ones (the process continues while there are events). When there are no more event to be processed, the control is returned back to the event demultiplexer by the event loop and the event demultiplexer blocks again while waiting for new operations to complete.

watch() is some arbitrary system call defined by me for the
purpose of this writing and could be
select()
in a real life scenario.

With this model, two things are very clear:

Blocking synchronous calls can only take place in the event demultiplexer which is outside of the event loop and,
No blocking call should take place inside the event loop.

When the event loop doesn't block, it gives the event demultiplexer the opportunity to receive new requests that performs an operation on a system resource. This way, an Express server can receive new request while it's amid the processing of a prior request. While it is guranteed that the processing of this prior request doesn't block, control can quickly be returned to the event loop to process the new request. Any request that should normally block while processing should be sent to the event demultiplexer and return.

Stuff can sometimes go south

The purpose of the event demultiplexer is defeated when the handler takes power which was given to it — and meant for it to use in due course — by the event loop and holds onto it or even plots a coup against the event loop to completely overthrow it from power.

The reactor pattern

Long before JavaScript had promises planned for the future (pun intended), the reactor pattern was what was adopted in handling asynchronous I/O operations. This was the only way to achieve concurrency. The reactor pattern is at the heart of Node.js

The reactor pattern simply associates an handler with each I/O operation. This handler is simply a callback function in JavaScript. The callback function is invoked as soon as an event is produced to the event loop. The event is processed and the associated handler is invoked.

const fs = require('fs')

fs.readFile('/path/to/some/file.js', (err, data) => {
  if (!err) {
    // do something with data
  }
})

The error is more important than the data. Node.js passes the error as the
first argument to force the API consumer to always check for error first
before reading data. So you don't fall into the trap of accessing an undefined data.

The reactor pattern as a way of achieving concurrency is only made possible in JavaScript by the event loop.

If you were going to build a chat app with Node and GraphQL?

Caleb Adepitan — Sun, 05 Jul 2020 16:16:18 +0000

I've been wondering and now I'm tired of wandering. So I'm going to ask this here, openly.

If you were going to build a chat application with Javascript (server-side, client-side) and GraphQL, what other tech stack will you use?
What database?
How will you speak to your database from your resolvers (I mean, is it with drivers or ORM, and please name the ORM or ORM-like tech)?

Your opinions are appreciated 🙏

Working with Binary like Decimal

Caleb Adepitan — Fri, 03 Jan 2020 06:37:36 +0000

Binary, hexadecimal and octal integers are the most common number bases generally used in computer science and computer science related fields.

Have you tried debugging a compiled C program, you'd either be looking at plain hexadecimals or Assembly instructions alongside the hexadecimal equivalent. Some people are so technical-savvy that they know what they are doing by just staring at hexadecimal, alternatively called an hexdump. Some will only understand what the hexadecimal is doing when they see the equivalent Assembly code. I won't lie, either way some don't know what is happening—Assembly is crazy it can make you too 😂😂.

The fun fact is; you don't need to debug a compiled C program or do reverse engineering before you need to understand these three beautiful number bases. You could just be a random programmer working Binary Manipulation like bit masks, shifting, turning on and off bits, to come to the realization that you need to know how these number systems work.

Binary

Binary integers like other digits are written from left to right—the most significant bit to least significant bit.

10001011 -> 139
^      ^
^      ^
^      least significant bit
most significant bit

I converted that binary number to it's decimal, in less than 10sec, just as I was writing, merely looking at it

The trick

You should know this if you've ever worked with binary numbers

Factor	Decimal	Binary
2⁰	1	1
2¹	2	10
2²	4	100
2³	8	1000
2⁴	16	10000
2⁵	32	100000
2⁶	64	1000000
2⁷	128	10000000
2⁸	256	100000000
2⁹	512	1000000000
2¹⁰	1024	10000000000
2¹¹	2048	100000000000
2¹²	4096	1000000000000

The power of 0 - 8 (1bit - 9bits) that is, 1 - 256, may be enough for you to know. At least for basic binary calculations.

I guess you have noticed a pattern already. Yes, let's assume 2⁰ as ground state. Every binary integer, that has at least a bit turned on, has this in them. So there is a 2⁰ in 2, 4, 8, ..., 2ⁿ.

The pattern

Every number except zero has a 1 ready state in its most significant bit, since every number contains a 2⁰.

The number of zeros 0 that follow the 1 from the most significant bit, is the power of 2. So 2¹ = 102 = 2.

The 1 from the most significant bit is owned by 2^0
The following 0 is accounted for, by the power on 2

The number of bits in a 2ⁿ number is n + 1, because the possible outcome of n number of bits ranges from 0 to 2ⁿ-1, not 1 to 2ⁿ, for all unsigned integers.

Decimal to Binary — Conversion

Let's pick some digits to make a decimal integer, say 13.
From our table, let's pick the closest number to this, 8, 2³ = 10002.
We have a variable temp = 1000, in binary. The remainder is 5.
The closest number to 5 from the table is 4, 1002.
Since the number is 5, we could simply say the remainder is 1 and add it to 1002, which gives 1012.
Alternatively, you could turn on the first turned-off bit from the least significant bit (rightmost side), and turn off the bit to the right of the one you turned on, if there is any.
```
10000 = 16
To add 1, turn on the rightmost 0, that is change it to 1
To give 10001 = 17

10001 = 17
To add 1, turn on the rightmost 0, and turn off the 1 closest to the 0 you turned on.
To give 10010 = 18

See the pattern:
10000 = 16
10    = 2
10000 + 10 = 10010 = 18.
```
So we add 5 = 101 to 8 = 1000 and we get 13 = 1101

Binary to Decimal — Conversion

Let's pick some bits to make a binary integer, say 10010011.
Break the bits from the rightmost side, and replace whichever bit you have taken with 0 in the original number
11 = 3, remainder = 10010000
10000 = 16, remainder = 10000000
10000000 = 128, remainder = 0
Add all: 128 + 16 + 3 = 147.

Something you need to know again, is the odd end of n number of bits, that is the 2ⁿ-1. Here is another table for that.

Factor - 1	Decimal	Binary
2¹ - 1	1	1
2² - 1	3	11
2³ - 1	7	111
2⁴ - 1	15	1111
2⁵ - 1	31	11111
2⁶ - 1	63	111111
2⁷ - 1	127	1111111
2⁸ - 1	255	11111111
2⁹ - 1	511	111111111
2¹⁰ - 1	1023	1111111111
2¹¹ - 1	2047	11111111111
2¹² - 1	4095	111111111111

At least you should know this from 1 - 255.

I hope you enjoyed this 😍. You can fav it here and follow me on twitter

The Radical JavaScript Contextmenu

Caleb Adepitan — Sun, 15 Dec 2019 13:45:53 +0000

You could skip this introduction

It has been forever now, that browser support has limited the amount of cool features we can use on the web. If you cared much about those people who are not privileged to get the latest browser, or due to some other reasons have defaulted in updating their browsers, you'd make your cool features fairly available to all users and keep the vast unsupported extra cool to your development machine. One must be discreet as to what platforms (clients) to support, counting the cost and knowing how it affects the public distribution and availability of your product.

The statistics of support should be estimated before incorporating features into your app or product.

Take for example a gas cooker and a microwave oven (as client), then a small metal dish, which is safe to use on a gas cooker and in an oven. Now, if you tried to replace all metal dishes with ceramic ones, because metal dishes makes too much noise when they collide with something, therefore a pollution to the community. Ceramic dishes are oven compatible but are not gas cooker compatible as they could crack. You would think twice before taking this action, counting the cost and doing the stats. of how many household in the community has a microwave oven.

The only solution we could provide to this problem over the years, is for one brilliant mind to come up with a library that finds alternative means to leverage all client when possible.

Contextmenu

Here today, I present to my fellow developers, who have cut a part out of the web architecture as their abode, The Radical Contextmenu.

The power of contextmenu in front-end design, although available on desktop devices, is not available to mobile devices. The reason for this is yet unknown to me. The contextmenu event works appropriately on desktop, but not on most mobile browsers.
A contextmenu as we all know is triggered by a right click on a desktop and a press-down on a mobile.

Although the contextmenu event doesn't work on mobile, this radical Javascript library Contextmenu has found alternative events pathway to achieve the same result, irrespective of your browser, as long as your browser supports the Touch and TouchEvents interface.

Contextmenu makes use of touch events in place of the contextmenu event. With the help of touch events a press-down is detected. The press-down can be controlled by setting a timeout—a timeout that determines a valid press-down. If a timeout of 800ms is specified, a press-down won't be initiated until an uninterrupted touch signal/gesture that lapses 800ms is detected.

The contextmenu interface provided by this library provides four positioning system.

absolute
fixed
relative
static

This positioning system is unrelated to the css positioning of the target element. See the documentation

Releases

There have been two releases recently. The first release, v0.1.0, was a faulty one, as the package name was not unique enough to be published on npm. This is corrected in the latest release, v0.1.1, and has made the first npm publication.

The API is still susceptible to frequent changes. Till a stable release: we can publish a v1.0 of the library.
Check it on Github, and please contribute with pull request, report bugs using the issue tracker, gracias.

A scrollspy in JavaScript—Vanilla flavoured

Caleb Adepitan — Sat, 10 Aug 2019 02:51:11 +0000

Many developers think a functionality embedded in a third party code must definitely be one hell of a thing to write for just any common developer. I tell you it's a big “NO!”.

One thing still holds true though; a third party code has probably been written with collaborations from different developers, and as such, would have been well structured.

Nonetheless, functional widgets for UI/UX are not really difficult to create. A secret you should know; “building a functional widget is a problem”. You will say I contradict myself—yeah, I think so too.

Think of it as a problem, and like every computer problem a solution is needed. This is where algorithms play in UI/UX designs.

Note: By functional widgets, I mean, a UI widget with scripted reactions to user interactions.

Understanding the problem.

We have a index of sections which can be navigated to in our TOC (table of contents).
Our problem is; we want to update which section in the TOC the user has scrolled onto.
Looking at it from an elevated angle this is a big problem.
Until we create a model!

Creating a model

Creating a model moves us from such elevated view, from a depressed position, to the same plane with the problem. Now we can leverage!
When creating a model we need to know what we have and pick what is useful. We have JavaScript. What is going to be useful?

a scroll event.
a scroll position (scrollTop).
the distance of each section from the offset of the page (offsetTop).
the element that makes the section; (HTMLHeadingElement). I'd be using h2-h4.

Now we need to know when the scrollTop is greater than or equal to the offsetTop of one of the headings at a particular instant.

Speak in codes

We are selecting h2-h4 because we consider h1 the big brother heading or a superior one, and h5-h6 the inferior ones, or better to say, not as significant as making up a section.

Note: I'll try as much as possible to go with es5 (way of doing things), wherever I consider necessary. Just because it's more conventional yet or so I think—ECMAScript(5X6)

(function() {
  const h2 = document.querySelectorAll("h2")
  const h3 = document.querySelectorAll("h3")
  const h4 = document.querySelectorAll("h4")
}());

We ain't done here yet and I noticed a problem already. How do we merge all three headings together. Remember each one of them is a NodeList, hence is iterable (not necessarily Iteration Protocols, but even with every regular for... loop). It's more like having an array.

Since we need to have them together, there is no other place to have them better than an array! This means they'll be like a sub-array in our collection—you can call it a multidimensional array.

(function() {
  const h2 = document.querySelectorAll("h2")
  const h3 = document.querySelectorAll("h3")
  const h4 = document.querySelectorAll("h4")
  let h = [h2, h3, h4]
}());

Yet, some other problems, we need to spread each of the NodeList into the array so we can have a linear array, and also we have lost ordering. The heading elements cannot be in the same order as they appeared in the HTML document that defined them as they don't have a common selector. We could possibly have had:

<h2>Heading 2</h2>
<p>This is a paragraph in a section...</p>

<h3>Heading 3</h3>
<p>This is a paragraph in another section...</p>

<h2>Heading 2</h2>
<p>This is a paragraph in, even, another section...</p>

If they were all h2 they would be selected in the right order also with respect to their offsetTop. But since there is an h3 amidst the h2 we would have the elements not ordered with respect to their offsetTop.

A solution we can think of is:

to loop through all the elements and give them a common class name, then re-select using that class name,
or get the offsetTop and sort. I prefer this for some reasons I don't know

To spread the NodeList returned from each of the selected element, we will flatten the array. Array.prototype.flat or the es6 Object spread ... would suffice, but let's code it raw.

const flatten = function flatten(arr) {
  const reduce = Array.prototype.reduce
  return reduce.call(arr, function(acc, val) {
    return Array.isArray(val) || typeof val[Symbol.iterator] === "function" ? acc.concat(flatten(val)) : acc.concat(val);
  }, [])
}

The arr parameter may not be an array, yet iterable, and as such will not have a reduce method. So we don't directly use arr.reduce, we rather call the method and give it a thisArg as the value for its this it will need to reference

(function() {
  const h2 = document.querySelectorAll("h2")
  const h3 = document.querySelectorAll("h3")
  const h4 = document.querySelectorAll("h4")
  let h = flatten([h2, h3, h4])
}());

Solution 1

Add a common class name and re-select. There could be an initial offset, probably due to the space your sticky navbar eats up

(function(offset) {
  const elOffsetIndex = {}
  const h2 = document.querySelectorAll("h2")
  const h3 = document.querySelectorAll("h3")
  const h4 = document.querySelectorAll("h4")
  let h = flatten([h2, h3, h4])

  // Time Complexity: O(n) => O(h.length)
  h.forEach(function(el) {
    el.className = "some-section"
  })

  h = document.querySelectorAll(".some-section")
  // now order is being kept

  window.addEventListener("DOMContentLoaded", function() {
    // without this event, the `offsetTop` value may not be right
    // as document may not have finished rendering
    const offsets = []

    // Time Complexity: O(n) => O(h.length)
    for (var i = 0; i < h.length; i++) {
      let hOffset = h[i].offsetTop + offset;
      offsets.push(hOffset);
      elOffsetIndex[hOffset] = h[i];
    }

    document.addEventListener("scroll", function() {
      const scrollTop = this.documentElement.scrollTop

      // Time Complexity: worst-case O(n) => O(offsets.length)
      for (var i in offsets) {
        if (scrollTop >= offsets[i]) {
          elOffsetIndex[offsets[i]].classList.add("active")
          break
        }
      }
    })
}(0));

The total time complexity for the above, using the Big O, in the worst-case is O(3n)

Solution 2

Sorting the offsetTop of the heading. We would be using a QuickSort algorithm to sort our array of offsets. The Quicksort has a best-case/average performance of O(n log n) and worst-case performance of O(n²).
With some optimizations, our sort should never get to the worst-case , as we should not encounter any repeating numbers which would mean no section is placed over the other.

Quicksort

const quickSort = function quickSort(data) { // no optimizations
  const partition = function partition(data, lo, hi) {
  const pivot = data[hi]
  let i = lo
  for (let j = lo; j < hi; j++) {
    if (data[j] < pivot) {
      data[i] = data[j] - data[i] + (data[j] = data[i]);
      i++
    }
  }
  // swap
  data[i] = data[hi] - data[i] + (data[hi] = data[i]);
    return i
  };
  const sort = function sort(data, lo, hi) {
    if (lo < hi) {
      let p = partition(data, lo, hi)
      sort(data, lo, p - 1)
      sort(data, p + 1, hi)
    }
  };
  sort(data, 0, data.length - 1)
}

(function(offset) {
  const elOffsetIndex = {}
  const h2 = document.querySelectorAll("h2")
  const h3 = document.querySelectorAll("h3")
  const h4 = document.querySelectorAll("h4")
  let h = flatten([h2, h3, h4])

  window.addEventListener("DOMContentLoaded", function() {
    // without this event, the `offsetTop` value may not be right
    // as document may not have finished rendering
    const offsets = []

    // Time Complexity: O(n) => O(h.length)
    for (var i = 0; i < h.length; i++) {
      let hOffset = h[i].offsetTop + offset;
      offsets.push(hOffset);
      elOffsetIndex[hOffset] = h[i];
    }

    // Time Complexity: O(n log(n)) => O(h.length log(h.length))
    quickSort(offsets)

    document.addEventListener("scroll", function() {
      const scrollTop = this.documentElement.scrollTop

      // Time Complexity: worst case O(n) => O(offsets.length)
      for (var i in offsets) {
        if (scrollTop >= offsets[i]) {
          elOffsetIndex[offsets[i]].classList.add("active")
          break
        }
      }
    })
}(0));

Note: all log is taken in log2

The total time complexity for the above, using the Big O, in the worst-case is O(2n + n log(n)) and rarely O(2n + n²). If rarely remains rarely, probably with some optimizations or not having an already ordered(sorted) offsets, then it is more efficient this way, otherwise...Thank you!

What is your convenient way of saying "$"?

Caleb Adepitan — Fri, 19 Jul 2019 20:44:33 +0000

I wonder a lot how y'all conveniently say "$" when you read codes.

Is it /dolar/.extend 'cause I use /es/.extend. $("div").html(...) = (s div dot html)

Object properties: Convert delimited strings to camelCase in JavaScript

Caleb Adepitan — Fri, 19 Jul 2019 01:43:53 +0000

Some few months ago, I took a project which was really nice and made me code happily.
It was a kind of project that had no dependencies specifically jQuery. What do you expect? I had to take the DOM in a vanilla flavour.

In the absence of jQuery and its Data API, I had to access the HTMLElement.dataset after the program had been fed the data attribute name.

In JavaScript, object properties, when using a dot notation, can only be accessed if the property name satisfies the naming convention of variables—I mean: containing [A-Za-z0-9_$]. More elaborately, [\w$]+[\d\w$]*.

The problem was that; the data-attribute in the markup uses hyphen as delimeter, but javascript won't allow this to be just that way in the native Object representation of the dataset. Instead some transformations are done to make it as it should be—camelCase.

That same problem was what I faced. The attribute name being fed to the program was also hyphenated. So I had to do the transformations myself and use index syntax to access it from the HTMLElement.dataset object.

The Transformation

The transformation came out of few lines of code that made an easy solution.

Thanks to @Order & Chaos Creative from the comment who made me realize we could actually use regular expression. This problem can be solved with two easy methods.

Method 1

function camelCase(name, delim = '-') {
  const list = Array.isArray(data) ? data : data.split(delim)
  return list.reduce((res, cur) => res + cur.charAt(0)
    .toUpperCase() + cur.slice(1)
  )
}

Our delim argument has a default value which is an hyphen. If the name has already been chunked into an array, we leave it to remain so, else we split it—at every occurrence of the delim—into an array. The best method to adopt is the array reduce, Array.prototype.reduce, since we do not need to transform the first word before an hyphen. We take the first char in the next word to upper case and slice out the rest, after which the strings are concatenated.

Method 2

function camelCase(name, delim = '-') {
  const pattern = new RegExp((delim + "([a-z])"), "g")
  return name.replace(pattern, (match, capture) => capture.toUpperCase())
}

Here we only capture the lowercase letter that comes after an hyphen, then pass an arrow function to the replace method as callback which takes the original match and the captured group. The captured string is what we need to transform to uppercase.

Application

We remove the "data-" prefix since we don't need it to access any prop in the dataset. It has a length of 5 units. Call the function and eureka!

const name = "data-hello-to-everyone"
const cutStart = 5
const newName = camelCase(name.substring(cutStart))
// newName: "helloToEveryone"

We can now get our property value.

const value = HTMLElement.dataset[newName]

Note: HTMLElement.dataset is not an object literal. It is a DOMStringMap Object.

interface HTMLElement {
  dataset: DOMStringMap;
}

I hope you enjoyed this short lesson. Don't forget to follow me here and on twitter, and drop your reactions plus comments.

What was the first thing you did with a programming language that made you happy?

Caleb Adepitan — Mon, 01 Jul 2019 18:46:22 +0000

I will start. In my early years of learning I wondered a lot how the web works.

The first thing that really made me happy was creating an hyperlink to my facebook page for people to like.
I put it on a dummy blog site I was using to practice HTML.

Feel free to tell me yours