Forem: Fernando González Tostado

AI Automated Engineers - Are We Doomed?

Fernando González Tostado — Mon, 18 Mar 2024 12:10:40 +0000

Not long ago, AI experts predicted that Software Engineers would eventually be automated by AI, just like many other professions. With the release of Devin, the first publicly introduced AI Software Engineer, the race has started, and there's been a lot of buzz (an interesting demos!) about it. Many developers, like other non-tech professionals, have started to worry.

Now, the question is not when, but how much and to what degree our jobs will be replaced by AI.

I've covered some of these topics in a past blog post, but as AI development has progressed many more thoughts have come to mind, I've discussed this topic with many people, and tried to be as updated as possible with the latest news so this is an updated and more comprehensive version of my thoughts on this topic.

The State of Software Engineering Automation

It all started with the release of ChatGPT at the end of 2023. It seems like this event was decades ago, but as a famous politician once said, "There are decades where nothing happens; and there are weeks where decades happen. (V. Lenin)". This is definitely the case. We were all amazed at how this chatbot could answer almost any question appropriately. For us engineers, it meant we didn't have to rely solely on Stack Overflow or other sources when googling, but rather use this tool as a comprehensive assistant to help us understand any concept or bug related to our software.

Not long after ChatGPT, GitHub Copilot was released. This was the second big step for engineers to have an AI tool directly embedded in our source code that could help us predict the next lines of code when given enough context. Eventually, Copilot Chat was also released, which, along with regular Copilot, was a perfect combo that gave us an extra productivity boost when writing or understanding our code.

Many other ChatGPT-like competitors have launched, like Claude, OLLama, nGrok, to name a few. We have almost daily breaking releases of new AI products that could affect how we work. The investment pace in AI is intense as venture capitalists work to beat one another, seeking big returns. This means a massive number of new AI tools are still in development and will potentially impact our work when released.

Can Developers Be Fully Automated?

That depends on the type of developer. This is a question that has been asked for a long time regarding many other professions. For example, some years ago when AutoCAD was released, many architects worried about their jobs. However, the reality is that AutoCAD didn't replace architects, but rather made them more productive and allowed them to use their energies on more creative tasks, rather than spending time drawing their concepts. While I think AI tools will have a bigger impact than any software tool released before, I believe to some degree, the same will happen with developers.

Some types of developers may be automated, for example, those who turn Figma designs into HTML or create simpler landing pages, and other similar tasks where the work involves using a few technologies for initial projects or proofs of concept will be the first to go. However, most of us developers with some years in the market know that a software developer is not a one-tool professional. We have to deal with people from different teams, several technologies across different versions, and generally, deal with problems that humans will (hopefully) only be able to solve. Even when existing full automation solutions are available now, they are not enough for handling some issues that machines can't solve. For example, Musk automated almost completely one of Tesla's gigafactories and had to roll back that decision as many issues arose where the machines couldn't solve problems that humans could.

Does the fact that AI tools partially replace us mean we'll have less work? Yes, definitely. We will be super-powered professionals who need less time to complete our work and therefore should be able to have more workload. No more time spent on stupid bugs caused by typos or unspotted silly errors, and more time on things that matter: architecture design, UX, business overview, best practices and patterns, etc. This twit from the Andrej Karpathy exdirector of AI in Tesla makes a great analogy with automated driving. Will there be fewer open positions for developers? Possibly; if more work could be done by fewer developers, why would any sane company overhire? The bright side is there's been a lot of discussion about potentially reducing the workweek for all tech developers, as discussed in this video. Even Musk has talked about a universal income for all humans since the decreased workload will give us less chance to work and earn money.

Finally, I think humans will still need to understand the basics, like a professor at my university once told me: "There are tools that already do this automatically, but to use them properly, you have to understand where the output comes from."

What About the Government?

Will they allow this flood of AI tools to replace workers worldwide? While highly criticized, the EU has been the first to start regulating AI as they consider some sensitive tasks should not be done by AI, regulate fake media content, and prevent uncompetitive actions by tech companies. They may also enforce companies to eventually reduce working hours and provide welfare for reduced salaries caused by lesser billed hours. Governments finally stepping in to enforce the correct use of AI will be crucial in determining the potential impact (positive or negative) on humanity. At this moment there's no regulation in place for them, therefore companies release them without any responsibility of potential harm they could cause, which in my opinion is a very dangerous situation and should be eventually regulated by governments. Here's an interesting podcast of an AI regulation advocate exposing why the Wild West state of product releases should be stopped.

It is widely known that some organizations like educational institutions (see here) and private companies are blocking the use of AI tools on their networks, and there is wide discussion about the ethical implications of using AI tools and how they could be correctly used. While AI offers potential benefits, there are valid concerns around academic integrity, data privacy, and responsible deployment that need to be addressed. My father is involved in Higher Education and this is a topic that we've discussed at length and there's no strategy to deal with it yet. The velocity of AI improvements is so high that it's hard to keep up with the latest tools, their implications and potential regulations.

What Should I Do to Protect Myself Against AI Automation?

Don't over-specialize: Unless you want to become an expert in one single technology, over-specializing is probably not the best option since AI would likely beat you in all ways. "In a wicked world, relying upon experience from a single domain is not only limiting, it can be disastrous." - David Epstein
Become a generalist: For me, this is the most viable option. Increasing your range of tools will make it very difficult for AI tools to replace you, since most will be made for solving specific problems. We've seen that existing models perform above average—sometimes better than most ordinary people on any topic you have in mind. However, only specialized AI tools are becoming the real threat to certain professions. This makes sense since most startups (not even OpenAI or other tech giants) don't have the scale to do everything perfectly. There will be different winners in each field or customer problem, therefore being a generalist is the way to go.
Become the master of the threats: By threats, I'm obviously referring to the AI tools. Learning and understanding these tools in detail will allow you to control those tools. You could become an in-demand developer if you become proficient with them. You don't have to become an AI scientist or similar. For example, I'm learning how to implement Langchain into existing code bases to solve complex problems that would otherwise have required very difficult algorithms, thus adding AI value to existing products.

Wrapping Up

The days when software engineers were the untouchable professionals with the highest salaries and best perks are long gone. We will be impacted (we've already been) by AI. The bright side? Opportunists and people who were around only for the good salaries will be out, relieving the pressure for all those developers passionate about software, with incredible tools to make their job much easier and enjoyable. The downside is we'll probably earn less money for doing what we love. Who knows, maybe less competition from those quitters will prevent salaries from dropping too much? In my case, I wasn't part of that cohort with awesome salaries from 10 years ago, so I'm kind of used to having a decent wage while working on exciting things I love doing.

I think of this as an era similar to the industrial revolution, which brought incredible tools that made life easier for many people and freeing them from repetitive tasks and increased the productivity of the world. While that revolution also brought a lot of pain and suffering to many people, it also brought a lot of opportunities for those who were able to adapt to the new times.

Cheer up! Rather than adopting a Neo-Luddite mentality and cursing the inventors of these tools, we should be happy to live in a time when they've just been released when we're still young and able to adapt to them and we still have a lot of freedom to use them in our favor. Some similar might probably never be repeated, and those who are one step ahead of the pack could forge a very bright future for themselves and their loved ones.

Email Overload? AI to the Rescue! A Practical Guide with OpenAI's Assistant API

Fernando González Tostado — Sun, 03 Dec 2023 22:05:40 +0000

Managing multiple Gmail accounts over the years, I've relied on Google Drivefor file backups and Google Photos for photo storage. Despite keeping my primary inbox tidy, Gmail's categorization often leaves non-inbox emails unread, creating a digital clutter I've ignored. Recently, this oversight forced me to invest in a Google One subscription as my Drive reached its capacity. Google's policy of limiting email activity when storage is full prompted me to find a solution. Manually sorting through years of emails seemed daunting, leading me to explore the potential of AI assistance.

The Assistant API with function calling tools recently grabbed my attention. After writing a blog post exploring its potential applications, I came across an X (former Twitter) post where someone claimed to have used the API to organize their email inbox. This intrigued me — it seemed like a practical solution for my email management challenges. However, the post didn't provide any code, making me think that this could be a useful tool for many others sharing the same issue. So I decided to dive into the googleapi and combine it with the OpenAI assistant API, testing it out with a real-world use case.

What will this code do?

The proposed code addresses the challenge of identifying and managing unread emails efficiently. It will analyze the latest unread emails in your inbox, categorizing them as spam/marketing or legitimate. Legitimate emails will be marked as read, while spam/marketing emails will be promptly deleted. This solution is designed for Gmail accounts, and users of other email providers will need to adapt the code to suit their specific APIs.

This proof of concept serves as a powerful tool, but I recommend exercising caution. Begin by testing it on a small dataset before scaling up to avoid potential data loss or other issues. I assume no responsibility for any consequences arising from the use of this code.

Gmail CRUD operations

I've taken the initial code from their Node.js quickstart guide, and added the functionality to mark as read, and delete emails. I won't go into much detail here since the code is pretty self-explanatory. Just follow the steps in the quick start guide and you should be good to go.

I think you'll have to create first a Google Cloud project. I already had one but it's fairly easy to create one. See steps here.

Adding required scopes to your app

While the quickstart guide mentions the readonly scope, our solution requires additional scopes (modify and delete). During the OAuth consent screen configuration, you can add these permissions for effective email management. I initially added all scopes, ensuring functionality, but precise scope knowledge is recommended for production implementation.

I honestly do enough research of which where the exact scopes that I needed, so I just added all of them which is obviously dangerous. For this like this why you should be careful when implementing this poc. If you know which ones are the exact ones please add them in the comments.

The googleapi code

The code below is the one that I used to get the emails from my inbox. I've added some comments to explain what each part does.

// email.ts
const fs = require('fs').promises;
const path = require('path');
const process = require('process');
const { authenticate } = require('@google-cloud/local-auth');
const { google } = require('googleapis');

// this gives ALL permissions to the app - USE WITH CAUTION
// app should be configured before running this script in the OAuth consent screen -> Scopes for Google APIs
// If modifying these scopes, delete token.json.
const SCOPES = ['https://mail.google.com/'];

// The file token.json stores the user's access and refresh tokens, and is
// created automatically when the authorization flow completes for the first
// time.
// the credentials.json file is the one downloaded from the google docs tutorial
const TOKEN_PATH = path.join(process.cwd(), 'token.json');
const CREDENTIALS_PATH = path.join(
  process.cwd(),
  'email-cleaner/credentials.json'
);

// Load credentials or create new credentials if none exist
async function loadSavedCredentialsIfExist() {
  try {
    const content = await fs.readFile(TOKEN_PATH);
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    return null;
  }
}

async function saveCredentials(client) {
  const content = await fs.readFile(CREDENTIALS_PATH);
  const keys = JSON.parse(content);
  const key = keys.installed || keys.web;
  const payload = JSON.stringify({
    type: 'authorized_user',
    client_id: key.client_id,
    client_secret: key.client_secret,
    refresh_token: client.credentials.refresh_token,
  });
  await fs.writeFile(TOKEN_PATH, payload);
}

export async function authorize() {
  let client = await loadSavedCredentialsIfExist();
  if (client) {
    return client;
  }
  client = await authenticate({
    scopes: SCOPES,
    keyfilePath: CREDENTIALS_PATH,
  });
  if (client.credentials) {
    await saveCredentials(client);
  }
  return client;
}

// get message details
async function getMessage(auth, id) {
  const gmail = google.gmail({ version: 'v1', auth });
  return gmail.users.messages.get({
    userId: 'me',
    id,
  });
}

// get all unread emails from the inbox
export async function listUnreadMessages(auth, qty = 10) {
  const gmail = google.gmail({ version: 'v1', auth });
  const res = await gmail.users.messages.list({
    userId: 'me',
    maxResults: qty,
    q: 'is:unread',
  });
  const messages = res.data.messages;
  if (!messages || messages.length === 0) {
    console.log('No messages found.');
    return;
  }

  let messagesWithDetails = [];
  for await (const message of messages) {
    // get message data
    const res = await getMessage(auth, message.id);
    messagesWithDetails.push({ id: message.id, snippet: res.data.snippet });
  }

  return messagesWithDetails;
}

// delete one or more messages
export async function deleteMessages(auth, ids: string | string[]) {
  const gmail = google.gmail({ version: 'v1', auth });

  if (Array.isArray(ids)) {
    return gmail.users.messages.batchDelete({
      userId: 'me',
      ids,
    });
  }

  return gmail.users.messages.delete({
    userId: 'me',
    id: ids,
  });
}

// mark one or more messages as read
export async function markAsRead(auth, ids: string | string[]) {
  const gmail = google.gmail({ version: 'v1', auth });

  if (Array.isArray(ids)) {
    return gmail.users.messages.batchModify({
      userId: 'me',
      ids,
      requestBody: {
        removeLabelIds: ['UNREAD'],
      },
    });
  }

  return gmail.users.messages.modify({
    userId: 'me',
    id: ids,
    requestBody: {
      removeLabelIds: ['UNREAD'],
    },
  });
}

Again, the above code is very similar to the one in the quickstart guide. I've added the deleteMessages and markAsRead functions only.

Setting up the OpenAI Assistant API

The Assistant API, unveiled during OpenAI's recent devday, empowers developers to construct AI assistants within their applications. An Assistant, equipped with instructions, harnesses models, tools, and knowledge to respond to user queries. Presently, the API supports three types of tools: Code Interpreter, Retrieval, and Function Calling. OpenAI plans to release more built-in tools and eventually enable users to introduce their own tools on the platform.

For this Proof of Concept (POC), I leveraged the function calling tool, offering the flexibility to invoke any desired function with specific inputs provided by the assistant. This flexibility renders the limits of the Assistant API nearly boundless.

The assistant setup was directly facilitated through the OpenAI Playground. I created a new assistant and incorporated the spam_message_filter function:

{
  "messages": {
    "type": "array",
    "description": "The list of messages to filter",
    "items": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The id of the message"
        },
        "snippet": {
          "type": "string",
          "description": "The snippet of the message"
        },
        "is_spam_or_marketing": {
          "type": "boolean",
          "description": "the decision"
        },
        "reason": {
          "type": "string",
          "description": "The reason why the message is spam"
        }
      },
      "required": ["id", "snippet", "reason", "is_spam_or_marketing"]
    }
  }
}

This function evaluates a list of messages and returns a categorized list with decisions on whether each message is spam, along with reasons for such classification.

To invoke this function, the assistant needs specific instructions. The provided instructions are straightforward:

You expertly filter emails for spam using advanced techniques. Given email IDs and snippets, your role is to swiftly provide an object for spam_message_filter with the array of messages. Invoke this function without engaging in conversation, and upon completion, simply finish the run with 'success' or 'failure'.

These instructions ensure the assistant operates without seeking clarification, executing the function and returning the result promptly. The code_interpreter tool must be toggled on for proper functionality.

Now, if we provide the assistant with an object like this

[
  {
    "id": "18b1f9b955819e62",
    "snippet": "With global server load balancing at ngrok, you can deliver faster and more reliable experiences for your end users. View in browser oct-2023-newsletter Product updates ngrok-newsletter-oct-"
  },
  {
    "id": "18b1f46604c9bc57",
    "snippet": "Discover a world-class developer experience with new platform features, fresh UI components, performance improvements, and more. stream-logo-1.png NEW RELEASES Discover a World-Class Developer"
  }
]

it will return an object like this

[
  {
    id: '18b1f9b955819e62',
    snippet: 'With global server load balancing at ngrok, you can deliver faster and more reliable experiences for your end users. View in browser oct-2023-newsletter Product updates ngrok-newsletter-oct-',
    is_spam_or_marketing: true,
    reason: 'Marketing content within newsletter snippet.'
  },
  {
    id: '18b1f46604c9bc57',
    snippet: 'Discover a world-class developer experience with new platform features, fresh UI components, performance improvements, and more. stream-logo-1.png NEW RELEASES Discover a World-Class Developer',
    is_spam_or_marketing: true,
    reason: 'Promotional content regarding new releases.'
  }
]

Note: While the Assistant API can be created directly from code (see here), I opted to create the assistant from the playground and use the assigned assistant ID in the code to maintain consistency and avoid creating a new assistant with each invocation.

The OpenAI Assistant API code

It's time to put everything together. The code below is the one that I used to get the emails from my inbox. I've added some comments to explain what each part does and I'll explain some important parts below.

import {
  authorize,
  deleteMessages,
  listUnreadMessages,
  markAsRead,
} from './email';
import { Thread } from 'openai/resources/beta/threads/threads';

// import the required dependencies
require('dotenv').config();
const OpenAI = require('openai');
const readline = require('readline').createInterface({
  input: process.stdin,
  output: process.stdout,
});

// Create a OpenAI connection
const apiKey = process.env.OPENAI_API_KEY;
const openai = new OpenAI({
  apiKey,
});

async function askQuestion(question: string) {
  return new Promise<string>((resolve, _reject) => {
    readline.question(question, (answer: string) => {
      resolve(`${answer}\n`);
    });
  });
}

type Message = {
  id: string;
  snippet: string;
  is_spam_or_marketing: boolean;
  reason: string;
};

async function initGmailAuth() {
  try {
    const auth = await authorize();
    return auth;
  } catch (error) {
    console.error(error);
    throw error;
  }
}

async function spamMessageFilter(messages: Message[], auth) {
  const delIds = messages
    .filter((message) => message.is_spam_or_marketing)
    .map((message) => message.id);

  // delete the messages
  deleteMessages(auth, delIds)
    .then(() => console.log('messages deleted', delIds))
    .catch(() => {
      // throw
      console.log('error deleting messages with ids', delIds);
    });

  const readIds = messages
    .filter((message) => !message.is_spam_or_marketing)
    .map((message) => message.id);

  // mark as read
  markAsRead(auth, readIds)
    .then(() => console.log('messages marked as read', readIds))
    .catch(() => {
      // throw
      throw new Error('error marking messages as read with ids', readIds);
    });
}

async function fetchLatestUnreadEmails(quantity: number = 10, auth) {
  return await listUnreadMessages(auth, quantity);
}

async function main() {
  // use the assistant created using the OpenAI playground
  const assistantId = process.env.OPENAI_SPAM_FILTER_ASSISTANT_ID;

  if (!assistantId) {
    throw new Error('OPENAI_SPAM_FILTER_ASSISTANT_ID not found');
  }
  const assistant = await openai.beta.assistants.retrieve(assistantId);

  // Log the first greeting
  console.log(
    "\nHello there, I'm your personal spam filter. I'll help you filter your emails.\n"
  );

  // this flag will be used prompt the user to continue or not
  let keepCleaning = true;
  // once a thread has been created, we can use the thread id to continue the conversation
  let threadId: string;
  while (keepCleaning) {
    // fetch the latest unread emails
    const gmailAuth = await initGmailAuth();

    // invoke the google api to fetch the latest unread emails
    const messages = await fetchLatestUnreadEmails(10, gmailAuth);
    if (Array.isArray(messages) && messages.length === 0) {
      console.log('Failed to fetch messages');
      return;
    }

    // create a thread
    let thread: Thread;
    if (!threadId) {
      thread = await openai.beta.threads.create();
    } else {
      thread = await openai.beta.threads.retrieve(threadId);
    }
    threadId = thread.id;

    console.log('starting thread with id: ', threadId);

    const messagesAsString = JSON.stringify(messages);
    await openai.beta.threads.messages.create(thread.id, {
      role: 'user',
      // todo?: when not passed as markdown, the assistant will not be able to parse the json
      content: `\`\`\`json\n${messagesAsString}\n\`\`\``,
    });
    console.log('thinking...');

    // use runs to wait for the assistant response and then retrieve it
    const run = await openai.beta.threads.runs.create(thread.id, {
      assistant_id: assistant.id,
    });

    let actualRun = await openai.beta.threads.runs.retrieve(thread.id, run.id);

    // polling mechanism to see if actualRun is completed
    // and we're ready to retrieve the assistant response
    // this should be made more robust.
    while (
      actualRun.status === 'queued' ||
      actualRun.status === 'in_progress' ||
      actualRun.status === 'requires_action'
    ) {
      // requires_action means that the assistant is waiting for the functions to be invoked
      // the model should provide a json object with the shape of the json objects above
      if (actualRun.status === 'requires_action') {
        // extra single tool call
        const toolCall =
          actualRun.required_action?.submit_tool_outputs?.tool_calls[0];

        const name = toolCall?.function.name;

        // parse the response from the assistant
        const args = JSON.parse(toolCall?.function?.arguments || '{}');
        const messages = args.messages;

        if (name === 'spam_message_filter') {
          await spamMessageFilter(messages, gmailAuth);
        } else {
          console.log('unknown function');
        }

        // we must submit the tool outputs to the run to continue
        await openai.beta.threads.runs.submitToolOutputs(thread.id, run.id, {
          tool_outputs: [
            {
              tool_call_id: toolCall?.id,
              output: JSON.stringify({ success: true }),
            },
          ],
        });
      }
      // keep polling until the run is completed
      await new Promise((resolve) => setTimeout(resolve, 2000));
      actualRun = await openai.beta.threads.runs.retrieve(thread.id, run.id);
    }

    // Get the last assistant message from the messages array
    const assisstantMessages = await openai.beta.threads.messages.list(
      thread.id
    );

    // Find the last message for the current run
    const lastMessageForRun = assisstantMessages.data
      .filter(
        (message) => message.run_id === run.id && message.role === 'assistant'
      )
      .pop();

    // If an assistant message is found, console.log() it
    if (lastMessageForRun) {
      // aparently this is not correctly typed
      // content returns an of objects do contain a text object
      const messageValue = lastMessageForRun.content[0] as {
        text: { value: string };
      };

      console.log(messageValue?.text?.value);
    }

    // ask if the user wants to continue
    const answer = await askQuestion('Do you want to continue? (y/n) ');
    if (answer.startsWith('n')) {
      keepCleaning = false;
    }
  }
}

main().catch(console.error);

There are some key parts that I will explain next. If you want to understand better the rest of the code, please you can take a look at my previous blog post.

The requires_action status means that the assistant has already processed the input and is waiting for the functions to be invoked. The model should provide a json object with the shape of the json objects above. The spam_message_filter function is the one that we created in the OpenAI playground. The spamMessageFilter function is the one that invokes the google api to delete and mark as read the emails.

if (actualRun.status === 'requires_action') {
  // extra single tool call
  const toolCall =
    actualRun.required_action?.submit_tool_outputs?.tool_calls[0];

  const name = toolCall?.function.name;

  // parse the response from the assistant
  const args = JSON.parse(toolCall?.function?.arguments || '{}');
  const messages = args.messages;

  // ...
}

Having the necessary information, we can invoke the spamMessageFilter function. This is a function that is created by us, and it can do anything we want. In this case, using the methods from the email.ts file we'll first delete the spam emails and then mark the remaining ones as read.

async function spamMessageFilter(messages: Message[], auth) {
  const delIds = messages
    .filter((message) => message.is_spam_or_marketing)
    .map((message) => message.id);

  // delete the messages
  deleteMessages(auth, delIds)
    .then(() => console.log('messages deleted', delIds))
    .catch(() => {
      // throw
      throw new Error('error deleting messages');
    });

  const readIds = messages
    .filter((message) => !message.is_spam_or_marketing)
    .map((message) => message.id);

  // mark as read
  markAsRead(auth, readIds)
    .then(() => console.log('messages marked as read', readIds))
    .catch(() => {
      // throw
      throw new Error('error marking messages as read');
    });
}

Finally, after submitting a success response to the assistant, we can continue looping and asking the user if they want to continue cleaning their inbox.

  const answer = await askQuestion('Do you want to continue? (y/n) ');
  if (answer.startsWith('n')) {
    keepCleaning = false;
  }

This should be enough for this PoC to work. You can try increasing the number of emails to be processed by changing the quantity argument from the fetchLatestUnreadEmails function.

Once you're sure that everything is working as expected, you could decrease the input tokens provided to the assistant, probably removing the reason and snippet properties from the Message type. This will reduce the cost of each call to the assistant.

If you want to see the full code, you can find it here

You can also take a look at my previous post where I explain in more dept how to build a chatbot that uses function calling with the assistant API.

Conclusion

The Assistant API with function calling tools is a powerful tool that can be used to automate many tasks. In this PoC, we've seen how we can use it to automate the process of cleaning our inbox from spam emails. This is just one of the many use cases that this API can be used for. I'm sure that we'll see many more in the future.

References

Build a chatbot with the new OpenAI Assistant API and Function Calling

Fernando González Tostado — Tue, 14 Nov 2023 01:13:30 +0000

Just a week has passed since the OpenAI Dev Conf 2023, and a surprising revelation unfolded: The Assistant's API. Unveiled in the latest OpenAI blog post, the Assistants API marks a significant stride in empowering developers to craft agent-like experiences within their applications.

In their own words:

Today, we’re releasing the Assistants API, our first step towards helping developers build agent-like experiences within their own applications. An assistant is a purpose-built AI that has specific instructions, leverages extra knowledge, and can call models and tools to perform tasks.

So, what does this mean for us? In essence, it means we now have the capability to construct our own AI assistants using the OpenAI API. This empowers us to harness the prowess of the GPT-4 model to execute tasks and answer questions with additional knowledge and context that we provide through uploaded documents (with no need for third-party involvement!), a Python code interpreter operating in a sandboxed environment, and a feature that truly caught my attention: function calling.

While functions themselves aren't novel, it's the way they've been implemented that truly stands out. In the past, calling a function meant uncertainty about the model's return, necessitating post-processing for the desired result — and even then, success wasn't guaranteed. Now, we can specify the desired function output, and the model will strive to provide a response aligning with the provided schema.

This newfound tool grants us immense flexibility and power, enabling our assistant to perform virtually any task — from sending emails to making calls and querying databases. The possibilities are limitless.

While the available documents and examples are still somewhat scarce, my curiosity led me to dive in and explore the potential. In this journey, I set out to build a simple math assistant, serving as a proof of concept for implementing function calls within the new Assistant API in Node.js.

For this example we'll initially create a simple quiz to test function calling and then we'll be able to keep the conversation going with the assistant to ask more questions while keeping the context of the conversation.

The implementation

For this example I've used the cookbook example provided by OpenAI and the command line strategy from this post from Ralf Elfving and I've tweaked it a bit to make it more interactive.

We'll just need a few basic things:

An OpenAI API key
A Node.js environment

We'll just need the openai and dotenv packages to get started:

npm install openai dotenv

Declare your API key as an environment variable: in your .env

OPENAI_API_KEY=your-api-key

Then, we can get started with the code:

// import the required dependencies
require('dotenv').config();
const OpenAI = require('openai');
const readline = require('readline').createInterface({
  input: process.stdin,
  output: process.stdout,
});

// Create a OpenAI connection
const secretKey = process.env.OPENAI_API_KEY;
const openai = new OpenAI({
  apiKey: secretKey,
});

We'll create a method and readlineto wait for user input

async function askRLineQuestion(question: string) {
  return new Promise<string>((resolve, _reject) => {
    readline.question(question, (answer: string) => {
      resolve(`${answer}\n`);
    });
  });
}

Now we'll create a main function to run our program. We'll start by creating the assistant.

This assistant will require the code_interpreter and function, tools, and we'll use the gpt-4-1106-preview model. I've experimented with the gpt-3.5-turbo-1106 model, but it doesn't seem to work as well as the gpt-4-1106-preview model.

I've abastracted the function call into a quizJson function that will return a JSON object with the quiz questions and answers just to make it easier to read.

const quizJson = {
  name: "display_quiz",
  description:
    "Displays a quiz to the student, and returns the student's response. A single quiz can have multiple questions.",
  parameters: {
    type: "object",
    properties: {
      title: { type: "string" },
      questions: {
        type: "array",
        description:
          "An array of questions, each with a title and potentially options (if multiple choice).",
        items: {
          type: "object",
          properties: {
            question_text: { type: "string" },
            question_type: {
              type: "string",
              enum: ["MULTIPLE_CHOICE", "FREE_RESPONSE"],
            },
            choices: { type: "array", items: { type: "string" } },
          },
          required: ["question_text"],
        },
      },
    },
    required: ["title", "questions"],
  },
};

async function main() {
  try {
    const assistant = await openai.beta.assistants.create({
      name: "Math Tutor",
      instructions:
        "You are a personal math tutor. Answer questions briefly, in a sentence or less.",
      tools: [
        { type: "code_interpreter" },
        {
          type: "function",
          function: quizJson,
        },
      ],
      // will work much better with the new model
      model: "gpt-4-1106-preview",
      // model: "gpt-3.5-turbo-1106",
    });

    // Log a first greeting
    console.log(
      "\nHello there, I'm Fernando's personal Math assistant. We'll start with a small quiz.\n",
    );

Once the assitant is created we'll create a thread, this will mantain the state of our conversation so we don't have to provide the context every time we ask a question. Remember that the model is stateless, so we need to provide the context every time we ask a question.

const thread = await openai.beta.threads.create();

To enable the application to run repeatedly, we'll employ a while loop. This loop will assess user input after each question to determine whether the user intends to continue or not. We'll also have a isQuizAnswered variable to keep track of the quiz state.

    // main method
    // create the assistant and the thread as mentioned above

    let continueConversation = true;
    let isQuizAnswered = false;

    while (continueConversation) {
      // logic

      // once done with the question-answer check if the user wants to continue
      const continueAsking = await askRLineQuestion(
        "Do you want to keep having a conversation? (yes/no) ",
      );

      continueConversation = continueAsking.toLowerCase().includes("yes");

      // If the continueConversation state is falsy show an ending message
      if (!continueConversation) {
        console.log("Alrighty then, I hope you learned something!\n");
      }
    }

The logic for the question-answer process will be as follows:

    while (continueConversation) {
      // first ask the question and wait for the answer
      // we'll initiate with a quiz and then we'll keep the conversation going
      const userQuestion = isQuizAnswered
        ? await askRLineQuestion("You next question to the model: \n")
        // this will make the model  build a quiz using our provided function
        : "Make a quiz with 2 questions: One open ended, one multiple choice" +
          "Then, give me feedback for the responses.";

      // Pass in the user question into the existing thread
      await openai.beta.threads.messages.create(thread.id, {
        role: "user",
        content: userQuestion,
      });

      // Use runs to wait for the assistant response and then retrieve it
      // Creating a run will indicate to an assistant that it should start looking at the messages in a thread and take action by calling tools or the model.
      const run = await openai.beta.threads.runs.create(thread.id, {
        assistant_id: assistant.id,
      });

      // then retrieve the actual run
      let actualRun = await openai.beta.threads.runs.retrieve(
        // use the thread created earlier
        thread.id,
        run.id,
      );

What comes next is a polling strategy to wait for the model to finish processing the response. This is a bit of a hack, but it works for now. We'll wait for the model to finish processing the response and then we'll retrieve it.

The expected cycle is as follows:

Previous to the quiz: The model will return a queued then an in_progress status while it's processing the response
Once the tool_calls are added for later use, the model will return a requires_action status. Here's where we'll actually execute the function.
Once the function is executed, we'll submit the tool outputs to the run to continue the conversation.
Finally, the model will return a completed status and we'll retrieve the response.
If the user wants to continue the conversation, we'll repeat the process but this time we'll skip the quiz and we'll just ask the user for a question.

      while (
        actualRun.status === "queued" ||
        actualRun.status === "in_progress" ||
        actualRun.status === "requires_action"
      ) {
        // requires_action means that the assistant is waiting for the functions to be added
        if (actualRun.status === "requires_action") {
          // extra single tool call
          const toolCall =
            actualRun.required_action?.submit_tool_outputs?.tool_calls[0];

          const name = toolCall?.function.name;

          const args = JSON.parse(toolCall?.function?.arguments || "{}");
          const questions = args.questions;

          const responses = await displayQuiz(name || "cool quiz", questions);

          // toggle flag that sets initial quiz
          isQuizAnswered = true;

          // we must submit the tool outputs to the run to continue
          await openai.beta.threads.runs.submitToolOutputs(
            thread.id,
            run.id,
            {
              tool_outputs: [
                {
                  tool_call_id: toolCall?.id,
                  output: JSON.stringify(responses),
                },
              ],
            },
          );
        }
        // keep polling until the run is completed
        await new Promise((resolve) => setTimeout(resolve, 2000));
        actualRun = await openai.beta.threads.runs.retrieve(thread.id, run.id);
      }

By this point we should have gotten a reponse from the model, so we'll display it to the user and then we'll ask if they want to continue the conversation.

      // once the run is completed, display the response
      console.log(actualRun.results[0].assistant_messages[0].content);

      // then ask if the user wants to continue
      const continueAsking = await askRLineQuestion(
        "Do you want to keep having a conversation? (yes/no) ",
      );

      continueConversation = continueAsking.toLowerCase().includes("yes");

      // If the continueConversation state is falsy show an ending message
      if (!continueConversation) {
        console.log("Alrighty then, I hope you learned something!\n");
      }
    }

Finally, we'll add the displayQuiz function. This function will take the name of the quiz and the questions and it will display them to the user. It will then wait for the user to answer the questions and then it will return the responses.

      // Get the last assistant message from the messages array
      const messages = await openai.beta.threads.messages.list(thread.id);

      // Find the last message for the current run
      const lastMessageForRun = messages.data
        .filter(
          (message) =>
            message.run_id === run.id && message.role === "assistant",
        )
        .pop();

      // If an assistant message is found, console.log() it
      if (lastMessageForRun) {
        // aparently the `content` array is not correctly typed
        // content returns an of objects do contain a text object
        const messageValue = lastMessageForRun.content[0] as {
          text: { value: string };
        };

        console.log(`${messageValue?.text?.value} \n`);
      }

To keep the conversation we have the option to again read the user input which will allows use to toggle off —if necessary— the continueConversation flag or repeat the process in a conversational manner.

      // then ask if the user wants to continue
      const continueAsking = await askRLineQuestion(
        "Do you want to keep having a conversation? (yes/no) ",
      );

      continueConversation = continueAsking.toLowerCase().includes("yes");

      // If the continueConversation state is falsy show an ending message
      if (!continueConversation) {
        console.log("Alrighty then, I hope you learned something!\n");
      }
    }

Don't forget to close the readline interface.

    readline.close();
  } catch (error) {
    console.error(error);
  }
}

Finally, we'll call the main function to run the program.

// call the main function after declaring it
main();

And the full main function will look like this:

async function main() {
  try {
    const assistant = await openai.beta.assistants.create({
      name: "Math Tutor",
      instructions:
        "You are a personal math tutor. Answer questions briefly, in a sentence or less.",
      tools: [
        { type: "code_interpreter" },
        {
          type: "function",
          function: quizJson,
        },
      ],
      // will work much better with the new model
      model: "gpt-4-1106-preview",
      // model: "gpt-3.5-turbo-1106",
    });

    // Log a first greeting
    console.log(
      "\nHello there, I'm Fernando's personal Math assistant. We'll start with a small quiz.\n",
    );

    // Create a thread
    const thread = await openai.beta.threads.create();

    // Use continueConversation as state for keep asking questions
    let continueConversation = true;

    while (continueConversation) {
      const userQuestion = isQuizAnswered
        ? await askRLineQuestion("You next question to the model: \n")
        // this will make the model  build a quiz using our provided function
        : "Make a quiz with 2 questions: One open ended, one multiple choice" +
          "Then, give me feedback for the responses.";

      // Pass in the user question into the existing thread
      await openai.beta.threads.messages.create(thread.id, {
        role: "user",
        content: userQuestion,
      });

      // Use runs to wait for the assistant response and then retrieve it
      const run = await openai.beta.threads.runs.create(thread.id, {
        assistant_id: assistant.id,
      });

      let actualRun = await openai.beta.threads.runs.retrieve(
        thread.id,
        run.id,
      );

      // Polling mechanism to see if actualRun is completed
      while (
        actualRun.status === "queued" ||
        actualRun.status === "in_progress" ||
        actualRun.status === "requires_action"
      ) {
        // requires_action means that the assistant is waiting for the functions to be added

        if (actualRun.status === "requires_action") {
          // extra single tool call
          const toolCall =
            actualRun.required_action?.submit_tool_outputs?.tool_calls[0];

          const name = toolCall?.function.name;

          const args = JSON.parse(toolCall?.function?.arguments || "{}");
          const questions = args.questions;

          const responses = await displayQuiz(name || "cool quiz", questions);

          // toggle flag that sets initial quiz
          isQuizAnswered = true;

          // we must submit the tool outputs to the run to continue
          await openai.beta.threads.runs.submitToolOutputs(
            thread.id,
            run.id,
            {
              tool_outputs: [
                {
                  tool_call_id: toolCall?.id,
                  output: JSON.stringify(responses),
                },
              ],
            },
          );
        }
        // keep polling until the run is completed
        await new Promise((resolve) => setTimeout(resolve, 2000));
        actualRun = await openai.beta.threads.runs.retrieve(thread.id, run.id);
      }

      // Get the last assistant message from the messages array
      const messages = await openai.beta.threads.messages.list(thread.id);

      // Find the last message for the current run
      const lastMessageForRun = messages.data
        .filter(
          (message) =>
            message.run_id === run.id && message.role === "assistant",
        )
        .pop();

      // If an assistant message is found, console.log() it
      if (lastMessageForRun) {
        // aparently the `content` array is not correctly typed
        // content returns an of objects do contain a text object
        const messageValue = lastMessageForRun.content[0] as {
          text: { value: string };
        };

        console.log(`${messageValue?.text?.value} \n`);
      }

      // Then ask if the user wants to ask another question and update continueConversation state
      const continueAsking = await askRLineQuestion(
        "Do you want to keep having a conversation? (yes/no) ",
      );

      continueConversation = continueAsking.toLowerCase().includes("yes");;

      // If the continueConversation state is falsy show an ending message
      if (!continueConversation) {
        console.log("Alrighty then, I hope you learned something!\n");
      }
    }

    // close the readline
    readline.close();
  } catch (error) {
    console.error(error);
  }
}

If you've created a new node project using npm init —recommended— you can add a script to run your project as follows

{
  "scripts": {
    "start": "ts-node yourFileName.ts"
  }
}

We can now run our program using npm start and we should get the following output:

Hello there, I'm Fernando's personal Math assistant. We'll start with a small quiz.

> Quiz:
 display_quiz
Question: What is the derivative of 3x^2?

      f'(x) = 6x
Question: What is the integral of x dx?

      Options: 0.5x^2 + C,x^2 + C,2x + C,None of these

      0.5x^2 + C

Your responses from the quiz:
 [ "f'(x) = 6x\n", '0.5x^2 + C\n' ]

Great work on the quiz! Your response to the first question, the derivative of \( 3x^2 \), is correct; it is \( 6x \).

For the second question, you correctly chose \( 0.5x^2 + C \) as the integral of \( x \) with respect to \( x \). Good job! Keep it up! 

Do you want to keep having a conversation? (yes/no) yes

You next question to the model: 
Why did you ask derivatives and integral question. A lot of years have passed since I've done any of those.

My apologies for selecting those math topics. It's common to use calculus questions in a math context, but I understand it might not be fresh in everyone's mind. If you have any other areas of interest or specific topics you'd like to review or learn about, please let me know, and I can tailor the content accordingly. 

Do you want to keep having a conversation? (yes/no) no
Alrighty then, I hope you learned something!

And that's it! We've created a simple math assistant that can answer questions and keep the conversation going. This is just a proof of concept, but it shows the potential of the new Assistant API. I'm sure we'll see more examples and use cases in the near future.

If you want to see the full code, you can find it in this repo

References

Building a Secure Next.js Application with Redux Toolkit Query and cookie tokens

Fernando González Tostado — Thu, 12 Oct 2023 18:30:51 +0000

Authentication and refresh tokens are essential for securing web applications. However, properly handling sessions and expirations can become a challenge. It's not always clear how to implement these features in a way that is both secure and user-friendly.

In this blog post I'll show you how to leverage from the phantastic Redux Toolkit Query library and web storage (cookies) to implement a robust authentication system that allows users to stay logged in for as long (almost) as they want without having to worry about expiring tokens or session timeouts.

Why Redux Toolkit and not React Query?

RQ is a great library for data fetching and caching, but RTKQ is more powerful and flexible. It gives us the full power of handling server state, similar to RQ, while also keeping the powerful features from Redux Toolkit.

What are authentication and refresh tokens?

Authentication tokens are used to verify that a user is who they say they are. They are typically generated by the server when a user logs in and are stored in the browser's local storage or session storage.

Usually authentication tokens are short-lived and expire after a certain amount of time. This is done for security reasons, so that if someone steals your token they can't use it forever. However, this can be inconvenient for users who want to stay logged in for longer periods of time. To solve this problem, refresh tokens are used. However, in this blog post we will focus on authentication tokens.

I like storing tokens in the cookies because they have expiration dates, security flags such as httpOnly, SameSite and Secure which make them less accessible to malicious actors whereas local storage is accessible to any script running on the page. Here is a great article explaining why cookies are better than local storage for storing tokens.

Using a wrapper layour strategy to persist authentication state

The wrapper layout strategy is a common approach to managing authentication state in Next.js applications. It involves creating a custom layout component that wraps all of your application's pages. This component checks the authentication status of the user and redirects them to the login page if they are not authenticated.

This approach has several benefits:

Simplicity: This approach to authentication management is relatively simple to implement, even for developers who are new to Redux Toolkit and Next.js.
Security: The wrapper layout strategy ensures that all pages of your application are protected by authentication. This helps to prevent unauthorized users from accessing your application's resources.
Usability: The refresh token mechanism ensures that users are not logged out unexpectedly if their access token expires. This improves the user experience by making it easier for users to stay logged in to your application.

Implementation

Enough theory, let's get our hands dirty. I expect you to have a basic understanding of Next.js, Redux Toolkit and Redux Toolkit Query and Next.js. You don't really need to have an API with authentication endpoints since we will mock the request and will focus on handling the tokens and the authentication state.

Setting up RTKQ

Considering that we have an existing Next.js with a Redux Toolkit store we will have the auth slice where we're going to set the authentication state and the user slice where we're going to store the user data.



// store/auth.ts

// this is how the API response could look like
type LoginResponse = {
  token: string;
  userEmail: string;
  userName: string;
  id: string;
};

const initialState: Partial<LoginResponse> = {};

const slice = createSlice({
  name: 'auth',
  initialState,
  reducers: {},
});

export const authReducer = slice.reducer;

Now lets setup the api slice. We will use the createApi function from RTKQ to create the api slice that will initially have a mutation for the login endpoint and a query for the user endpoint which will be used to get the user data when the user comes back to the application and his token is still valid.



// store/authApi.ts
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const authApi = createApi({
  reducerPath: 'authApi',
  baseQuery: fetchBaseQuery({
    baseUrl:
      typeof window === 'undefined'
        ? 'http://localhost:3000'
        : window.location.origin,
  }),
  endpoints: (builder) => ({
    login: builder.mutation<LoginResponse, { userName: string, password: string }>({
      query: ({ userName, password }) => ({
        url: '/api/login',
        method: 'POST',
        body: {
          userName,
          password,
        },
      }),
    }),
    getAuthData: builder.query<LoginResponse, { token: string }>({
      query: ({ token }) => ({
        url: 'api/auth-details',
        // this is the default but I'm leaving it here for reference
        method: 'GET',
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }),
    }),
  }),
});

export const { useLoginMutation, useGetAuthDataQuery } = authApi;

Now we need to add the api matchers to the auth slice so that we can update the state when the login or getAuthData endpoints are called. The matchFulfilled matcher will be used to update the state when the request is successful. There are other matchers (info ) that can be used to update the state when the request is rejected or pending.

We'll also declare a setAuthCookie method that will base64 encode and store the token in the browser cookies. I like the cookies-next library for this but you can use any other library or even the native document.cookie API.



import { setCookie } from 'cookies-next';
import { createSlice } from '@reduxjs/toolkit';

// store/auth.ts
const setAuthCookie = (token: string, name: string) => {
  const toBase64 = Buffer.from(token).toString('base64');

  setCookie(name, toBase64, {
    maxAge: 30 * 24 * 60 * 60,
    path: '/',
    // more security options here
    // sameSite: 'strict',
    // httpOnly: true,
    // secure: process.env.NODE_ENV === 'production',
  });
};

const slice = createSlice({
  name: 'auth',
  initialState,
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addMatcher(
        authApi.endpoints.login.matchFulfilled,
        (_state, { payload }) => {
          // set the token in the cookies
          setAuthCookie(payload.token, 'auth_token');

          // store the user data in the store
          // "mutation" also works
          // state = payload;
          return payload;
        }
      )
      .addMatcher(
        authApi.endpoints.getAuthData.matchFulfilled,
        (_state, { payload }) => {
          // in case we receive a new token when refetching the details
          setAuthCookie(payload.token, 'auth_token');
          return payload;
        }
      );
  },
});

Lets declare some helpers to get the cookies and return possible valid tokens.



// lib/cookies.ts
import { getCookie } from 'cookies-next';

// helpers to get cookies
const getAuthCookie = (name: string) => {
  const cookie = getCookie(name);

  if (!cookie) return undefined;

  return Buffer.from(cookie, 'base64').toString('ascii');
};

export const getValidAuthTokens = () => {
  const token = getAuthCookie('auth_token');

  const now = new Date();
  const tokenDate = new Date(token || 0);

  return {
    token: now < tokenDate ? token : undefined,
  };
};

Setting up the wrapper

Finally, it's time to create the wrapper layout component. This component will be used to wrap all of our application's authenticated pages. It will check the authentication status of the user, if it finds a valid token and no auth details in the store it will call the getAuthData endpoint to get the user data and update the store. If it doesn't find a valid token it will delete any possibly existing token and redirect the user to the login page.



// components/AuthWrapper.tsx
import { useRouter } from 'next/router';
import { useDispatch, useSelector } from 'react-redux';
import { getValidAuthTokens } from '@/lib/cookies';

type Props = {
  children?: React.ReactNode;
};

export const AuthWrapper = ({ children }: Props) => {
  const dispatch = useDispatch();
  const { push } = useRouter();
  const { userEmail } = useSelector((state: RootState) => state.auth);

  const { token } = getValidAuthTokens();

  // this query will only execute if the token is valid and the user email is not already in the redux store
  const { error, isLoading } = useGetAuthDataQuery(
    { token: token || '' },
    {
      // The useGetAuthDataQuery hook will not execute the query at all if these values are falsy
      skip: !!userEmail || !token,
    }
  );

  // if the user doesnt have a valid token, redirect to login page
  useEffect(() => {
    if (!token) {
      push('/login');
      // will explain this in a moment
      dispatch(logout());
    }
  }, [token, push]);

  // optional: show a loading indicator while the query is loading
  if (isLoading) {
    return <div>Loading...</div>;
  }

  return children;
};

The key in this component is using the skip option in the useGetAuthDataQuery hook. This option allows us to skip the execution of the query if the token is not valid or if the user info (we used userEmail but you could use any other auth property) is already in the store. This is important because we don't want to execute the query every time the user navigates to a wrapped route. We only want to execute this query when the user comes back -eg. reloading- to the application and his token is still valid.

We can also make use of the cache feature of RTQK keepUnusedDataFor to keep the user data in the cache for a certain amount of time.

We can wrap all the routes that should be authenticated using the Page.getLayout feature from Next.js. This will allow us to wrap all the pages that should be authenticated with the AuthWrapper component.



// pages/some-protected-page.tsx
export default function SomeProtectedPage() {
  return (
    <div>
      <h1>Some protected page content</h1>
    </div>
  );
}

Page.getLayout = function getLayout(page) {
  return <AuthWrapper>{page}</AuthWrapper>;
};

This should be enable in _app.tsx so that it applies to all the pages. More info about per page getLayout here.



// pages/_app.tsx
import { store } from '@/store';
import { Provider } from 'react-redux';

export default function MyApp({ Component, pageProps }) {
  // Use the layout defined at the page level, if available
  const getLayout = Component.getLayout || ((page) => page);

  return (
    <Provider store={store}>{getLayout(<Component {...pageProps} />)}</Provider>
  );
}

You can also individually wrap every protected page with the AuthWrapper component. This approach is also valid, however I don't find it as clean as the previous one.



// pages/protected-page.tsx
const ProtectedPage = () => {
  return (
    <AuthWrapper>
      {
        // page content
      }
    </AuthWrapper>
  );
};

Finally, adding the logout action to the auth slice will allow us to clear the cookies and the store when the user logs out. We will not create an api endpoint —therefore we will declare the action in the reducers keys— for this since we don't need to make a request to the server to log out. But depending on your use case you might want to create an api endpoint for this with its corresponding api matcher.



// store/auth.ts
import { removeCookie } from 'cookies-next';

const slice = createSlice({
  name: 'auth',
  initialState,
  reducers: {
    logout: () => {
      removeCookie('auth_token');
      // clear the auth slice data
      return {};
    },
  },
  extraReducers: (builder) => {
    // here we have the api matchers — login and getAuthData
  },
});

If you wish to see a PoC implementation you can find it here

Conclusion

Redux Toolkit Query is a powerful library that can be used to simplify authentication management in Next.js applications. By using the wrapper layout strategy, you can easily implement a robust authentication system that is both secure and user-friendly. If you have some previous experience using Redux (React Query experience helps too!) in any form, you should be able to implement this approach without much trouble.

Photo from Edan Cohen at Unsplash

How to Build a Contextual Chatbot with LangChain and PostgreSQL + Drizzle ORM

Fernando González Tostado — Sun, 02 Jul 2023 15:28:13 +0000

Have you ever wanted to have a chatbot that could understand the context of a conversation and a document? For example, imagine you're reading a document about how to build a chatbot, and you have a question about a specific step. You could ask your chatbot the question, and it would be able to answer you without you having to copy and paste anything.

This is what contextual chats are all about. They allow you to have a natural conversation with a chatbot, even if the chatbot is not familiar with the topic of the conversation.

Contextual chats are made possible by a combination of technologies, including LangChain, PostgreSQL, and Drizzle.

LangChain is a framework that makes it easy to interact with language models.
PostgreSQL is a database that can be used to store documents.
Drizzle is an ORM that can be used to query documents in PostgreSQL.

In this tutorial, we will show you how to build a contextual chatbot using these technologies. We will start by creating a simple chatbot that can answer questions about documents. Then, we will show you how to use LangChain to interact with a language model, PostgreSQL to store documents, and Drizzle to query documents.

By the end of this tutorial, you will have an idea of how to build a working contextual chatbot that can answer questions about documents. You will also have a better understanding of how these technologies can be used to build contextual chatbots.

In my case I wanted the interface to accept a PDF file and upload it to the database and it looked like this:

With no further ado, let's get started!

For this tutorial you should be familiar with Typescript, PostgreSQL and Drizzle (or similar ORMs like PRisma) and probably NextJS but you can adapt this tutorial to any other framework since we'll focus on the backend only

I don't want to make this post too long adding frontend code. I used this project as a base for the frontend and adapted the backend to support the upload and query of documents to have it working with a contextually aware chatbot.

Our Drizzle model will contain a parent document LangChainDocs and a child document Docs. The parent document will contain the name of the document and the child document will contain the metadata and the content of the document.



// your-drizzle-model.ts
import { relations } from 'drizzle-orm';
import { pgTable, text, varchar } from 'drizzle-orm/pg-core';

export const langChainDocs = pgTable('LangChainDocs', {
  id: varchar('id').primaryKey(),
  createdAt: text('createdAt'),
  name: text('name'),
  nameSpace: text('nameSpace'),
});

export const langChainDocRelations = relations(langChainDocs, ({ many }) => ({
  docs: many(docs),
}));

export const docs = pgTable('Docs', {
  id: varchar('id').primaryKey(),
  createdAt: text('createdAt'),
  metadata: text('metadata'),
  pageContent: text('pageContent'),
  name: text('name'),
  langChainDocsId: text('langChainDocsId'),
});

export const docsRelations = relations(docs, ({ one }) => ({
  langChainDocs: one(langChainDocs, {
    fields: [docs.langChainDocsId],
    references: [langChainDocs.id],
  }),
}));

// your-drizzle-db.ts
export const drizzleDb = drizzle(client, { schema });
// more of how to setup drizzle in https://drizzle.dev/docs/#getting-started

Then we'll have a route that will upload a document to our database only if this document doesn't exist already. We don't want repeated documents in our database for obvious reasons.

From the client the request will be something like this:



const formData = new FormData();

// some existing document of the type of File
formData.append('file', file);

const response = await fetch('/api/upload', {
  method: 'POST',
  // you'll probably have to add the multipart/form-data header
  body: formData,
});

Then in the backend we'll parse the file with the multiparty library, this will give us the file name and the path of the file in the server local storage.



// api/upload.ts
import { Form } from 'multiparty';

export default async function handler(
  req: ApFDataRequest,
  res: NextApiResponse,
) {
  const form = new Form();
  const formData = await new Promise<FData>((resolve, reject) => {
    form.parse(req, (err, fields, files) => {
      if (err) {
        reject(err);
        return;
      }

      const file = files.file[0];
      resolve({ file });
    });
  });

  const fileName = formData.file.originalFilename;
  const filePath = formData.file.path;

Once having the parsed file we'll query the database to see if the document already exists. If it doesn't exist we'll upload it to the database and we'll return the document name to the client.



// api/upload.ts
import { getExistingDocs } from 'your-backend';

const DBDocs = await getExistingDocs(fileName);

// somewhere in your backend or directly in the api/upload.ts file
export const getExistingDocs = async (fileName: string) => {
  const document = await drizzleDb.query.langChainDocs.findMany({
    where: eq(schema.langChainDocs.name, fileName),
    with: {
      docs: true,
    },
  });

  return document;
};

back in the api/upload.ts file we'll check the document.length to see if the document already exists in the database.



const DBDocs = await getExistingDocs(fileName);
const fileExistsInDB = DBDocs.length > 0;

if (!fileExistsInDB) {
  // upload the document to the database
} else {
  // return the document name to the client
}

Now it's time to parse the file in a way that Langchain can understand and upload it to the database.



// somewhere in your backend or directly in the api/upload.ts file
import { Document } from 'langchain/document';
import { PDFLoader } from 'langchain/document_loaders/fs/pdf';
import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';

const getPdfText = async (
  // the path of the file in the server local storage
  filePath: string
): Promise<Document<Record<string, any>>[]> => {
  const loader = new PDFLoader(filePath);

  const pdf = await loader.load();

  // split into chunks
  const textSplitter = new RecursiveCharacterTextSplitter({
    chunkSize: 1000,
    chunkOverlap: 200,
  });

  // this outputs an array of the type of Document objects
  // https://docs.langchain.com/docs/components/schema/document
  const docs = await textSplitter.splitDocuments(pdf);

  return docs;
};

with the parsed document we can now upload it to the database using Drizzle ORM



const drizzleInsertDocs = async (
  docsToUpload: Document[],
  fileName: string
) => {
  await drizzleDb.transaction(async () => {
    const newDocId = randomUUID();

    await drizzleDb
      .insert(langChainDocs)
      .values({
        id: newDocId,
        name: fileName,
        nameSpace: fileName,
      })
      .returning();

    await drizzleDb.insert(docs).values(
      docsToUpload.map((doc) => ({
        id: randomUUID(),
        name: fileName,
        // metadata is a JSON object thus we need to stringify it
        metadata: JSON.stringify(doc.metadata),
        pageContent: doc.pageContent,
        langChainDocsId: newDocId,
      }))
    );
  });
};

and they are invoked like this:



export const langchainUploadDocs = async (
  filePath: string,
  fileName: string
) => {
  const docs = await getPdfText(filePath);

  await drizzleInsertDocs(docs, fileName);
};

all together the api/upload.ts file will look like this:



import type { NextApiRequest, NextApiResponse } from 'next';
import { Form } from 'multiparty';

import { langchainUploadDocs } from '@/utils/langchain';
import { getErrorMessage } from '@/utils/misc';
import { getExistingDocs } from '@/utils/drizzle';

export const config = {
  api: {
    bodyParser: false,
  },
};

interface FData {
  file: {
    fieldName: string;
    originalFilename: string;
    path: string;
    headers: {
      [key: string]: string;
    };
    size: number;
  };
}

interface ApFDataRequest extends NextApiRequest {
  body: FData;
}

export type UploadResponse = {
  fileExistsInDB: boolean;
  nameSpace: string;
};

export default async function handler(
  req: ApFDataRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    res.status(405).json({ error: 'Method not allowed' });
    return;
  }
  const form = new Form();
  const formData = await new Promise<FData>((resolve, reject) => {
    form.parse(req, (err, fields, files) => {
      if (err) {
        reject(err);
        return;
      }

      const file = files.file[0];
      resolve({ file });
    });
  });

  const fileName = formData.file.originalFilename;
  const filePath = formData.file.path;

  try {
    const DBDocs = await getExistingDocs(fileName);
    const fileExistsInDB = DBDocs.length > 0;

    if (!fileExistsInDB) {
      try {
        await langchainUploadDocs(filePath, fileName);
      } catch (error) {
        const errMsg = getErrorMessage(error);
        res.status(500).json({ error: errMsg });
        return;
      }
    }

    const resData: UploadResponse = {
      fileExistsInDB: !!fileExistsInDB,
      nameSpace: fileName,
    };

    res.status(200).json(resData);
  } catch (error) {
    const errMsg = getErrorMessage(error);
    res.status(500).json({ error: errMsg });
    return;
  }
}

Please remember that I'm using the NextJS routes api so you'll have to adapt this code to your framework of choice.

Great, we now have a file uploaded to our database. Now it's time to query the database to get the document and the metadata of the document and use it to have a conversation with our chatbot using the tools that Langchain provides us.

Back in the client, we've received a response from the server with the name of the document. We'll use this name to call the api/chat route for the actual contextual conversation

The client will send to the server a request like this:



// shape of the request
interface ReqBody {
  question: string;
  history: Array<Array<string>>;
  nameSpace: string;
}

// 1st iteration of the conversation
// question: 'Please give me an overview of the document',
const req = {
  question: 'Please give me an overview of the document',
  history: [],
  nameSpace: 'tasty-cakes.pdf',
};

// 2nd iteration of the conversation
const req = {
  question: 'Do they have chocolate?',
  history: [
    [
      'Please give me an overview of the document',
      'The document is about tasty cakes',
    ],
  ],
  nameSpace: 'tasty-cakes.pdf',
};

// 3rd iteration of the conversation
const req = {
  question: 'Do they have vanilla?',
  history: [
    [
      'Please give me an overview of the document',
      'The document is about tasty cakes',
    ],
    ['Do they have chocolate?', 'Yes, they have chocolate'],
  ],
  nameSpace: 'tasty-cakes.pdf',
};

// and so on...

Which will be sent to the server like this:



const response = await fetch('/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(req),
});

Then back in our api/chat.ts file we'll parse the request and query the database to get the document and the metadata of the document.



// use the nameSpace to query the database with our getExistingDocs function
const DBDocs = await getExistingDocs(nameSpace);

// we must arrange them in a way that Langchain can understand using the Document class
import { Document } from 'langchain/document';

const documents = sqlDocs[0].docs.map(
  (doc) =>
    new Document({
      metadata: JSON.parse(doc.metadata as string),
      pageContent: doc.pageContent as string,
    })
);

We've also have to arrange the chat history in a way that Langchain can understand:



// api/chat.ts
import {
  AIChatMessage,
  BaseChatMessage,
  HumanChatMessage,
} from 'langchain/schema';

const chatHistory: BaseChatMessage[] = [];
history?.forEach((_, idx) => {
  // first message is always human message
  chatHistory.push(new HumanChatMessage(history[idx][0]));
  // second message is always AI response
  chatHistory.push(new AIChatMessage(history[idx][1]));
});

We'll use the HNSWLib library to embed locally the documents in a vector space. This will allow us to query the database for the most similar document to the question that we're asking.



// api/chat.ts
const HNSWStore = await HNSWLib.fromDocuments(
  documents,
  new OpenAIEmbeddings()
);

The we'll create something called chain (add small description):



// somewhere in your backend or directly in the api/chat.ts file
import { OpenAI } from 'langchain/llms/openai';
import { ConversationalRetrievalQAChain } from 'langchain/chains';
import { VectorStore } from 'langchain/dist/vectorstores/base';

const CONDENSE_PROMPT = `Given the following conversation and a follow up question, rephrase the follow up question to be a standalone question.

Chat History:
{chat_history}
Follow Up Input: {question}
Standalone question:`;

const QA_PROMPT = `You are a helpful AI assistant. Use the following pieces of context to answer the question at the end.
If you don't know the answer, just say you don't know. DO NOT try to make up an answer.
If the question is not related to the context, politely respond that you are tuned to only answer questions that are related to the context.

{context}

Question: {question}
Helpful answer in markdown:`;

export const makeChain = async (vectorStore: VectorStore) => {
  const model = new OpenAI({
    temperature: 0.9, // increase temepreature to get more creative answers
    modelName: 'gpt-3.5-turbo', //change this to gpt-4 if you have access
    openAIApiKey: process.env.OPENAI_API_KEY,
  });

  return ConversationalRetrievalQAChain.fromLLM(
    model,
    vectorStore.asRetriever(),
    {
      qaTemplate: QA_PROMPT,
      questionGeneratorChainOptions: { template: CONDENSE_PROMPT },
      returnSourceDocuments: true, // optional
    }
  );
};

and we invoke the chain like this:



const HNSWStore = await HNSWLib.fromDocuments(
  documents,
  new OpenAIEmbeddings()
);

const chain = await makeChain(HNSWStore);

// Sanitize the question since OpenAI recommends replacing newlines with spaces for best results
const sanitizedQuestion = question.trim().replaceAll('\n', ' ');
const response = await chain.call({
  question: sanitizedQuestion,
  chat_history: chatHistory || [],
});

The response will return a text string and an array of Document objects make of which chunk of the document the LLM used to answer the question.



type Response = {
  // 'The document is about tasty cakes'
  answer: string;
  sourceDocuments: Document[];
};

That was it. Apologies for the long post but I wanted to make sure that I covered all the steps to make this work.

Here's the source code of a working example in case you want to play with, check more details and -hopefully- improve it!

Conclusion

In this tutorial, we have shown you how to build a contextual chatbot using LangChain, PostgreSQL, and Drizzle. We started by creating a simple chatbot that could answer questions about documents. Then, we showed you how to use LangChain to interact with a language model, PostgreSQL to store documents, and Drizzle to query documents.

By the end of this tutorial, you have a working contextual chatbot that can answer questions about documents. You also have a better understanding of how these technologies can be used to build contextual chatbots.

Here are some of the next steps that you can take:

Improve the chatbot's ability to answer questions. You can do this by training the language model on a larger dataset of documents.
Add more features to the chatbot. For example, you could add the ability to generate summaries of documents, or the ability to answer open-ended questions.
Deploy the chatbot to a production environment. This would allow you to share the chatbot with others and gather feedback.

I hope you enjoyed this tutorial!

Bonus

Query and update with Prisma ORM



// schema.prisma.ts

model LangChainDocs {

  id        String   @id @default(uuid())

  createdAt DateTime @default(now())

  name      String

  nameSpace String

  docs      Docs[]

}

model Docs {

  id              String        @id @default(uuid())

  createdAt       DateTime      @default(now())

  metadata        String // json string

  pageContent     String

  name            String

  docs            LangChainDocs @relation(fields: [langChainDocsId], references: [id])

  langChainDocsId String

}

// for uploading documents to the database

const prismaInsertDocs = async (docsToUpload: Document[], fileName: string) => {

  await prisma.langChainDocs.create({

    data: {

      name: fileName,

      nameSpace: fileName,

      docs: {

        create: docsToUpload.map((doc) => ({

          name: fileName,

          metadata: JSON.stringify(doc.metadata),

          pageContent: doc.pageContent,

        })),

      },

    },

  });

};

// for querying the database

export const getDocumentsFromDB = async (fileName: string) => {

  const docs = await prisma.langChainDocs.findFirst({

    where: {

      name: fileName,

    },

    include: {

      docs: true,

    },

  });

return docs;

};

Sources:

As Isaac Newton said: "If I have seen further it is by standing on the shoulders of Giants".

Most of the frontend has been kept as is from the original project that I used to get started with Langchain and made a number of changes to make it work using PostgreSQL and Drizzle ORM.

Foto from Juri Gianfrancesco at Unsplash

Adapting to New Challenges: How to Learn and Thrive in Unfamiliar Territory

Fernando González Tostado — Thu, 15 Jun 2023 01:27:59 +0000

When I started my career and decided on my stack (Node.js and React), I dedicated all my efforts to becoming proficient in those technologies. I firmly believed that if an opportunity arose to explore something beyond my stack, I would decline it to avoid distraction from my primary focus. I was determined to specialize and avoid diversions. It is widely recognized that as a junior developer, concentrating on a single stack is an optimal approach, and straying from it should be avoided until one feels proficient. However, a professional career is rarely a straightforward path, and being prepared for unexpected challenges is crucial.

In my recent post, I explained my point of view of how the rise of AI has impacted professional development and how it has become increasingly apparent that being exceptionally skilled in a single language or stack may no longer hold the same professional value. While it remains essential to possess strong problem-solving abilities in general programming, companies often expect professionals to adapt to new challenges and learn different languages and technologies. This has been my recent experience, especially when joining a new company or team.

Joining a new company or team presents exciting opportunities for professional growth. However, it is not uncommon to encounter tasks or responsibilities that lie outside of one's area of expertise. Initially, this can be a daunting situation, particularly if you possess limited knowledge or experience in the required domain. Failing to adopt the right mindset and strategy can burden your daily work and potentially impact your career. In this post, we will explore a step-by-step approach that has consistently helped me effectively tackle unfamiliar challenges and embrace continuous learning.

However, one day, shortly after joining a new company, I was unexpectedly assigned the task of implementing a feature in Golang. Golang was not part of my stack, and to be honest, I had no desire to learn it. In my previous roles, I had always worked as a frontend engineer, and my closest encounter with Golang was in a React project where it was used for the backend. However, I never delved into the backend code as there was a dedicated developer for that aspect. I had convinced myself that I would never have to work with Golang, as my intention was to solely focus on my chosen stack.

Normally, I would stay within my comfort zone, relying on someone else specialized in that area to handle any backend-related challenges. Therefore, this new solicited implementation scared me a lot and sparked self-doubt. I even questioned whether I was in the right place if I had to work on something unrelated to my stack, and various other childish questions crossed my mind. However, I soon realized that this was an opportunity to learn something new and expand my skill set.

With the right approach, I could overcome this challenge and thrive in unfamiliar territory.

The following steps outline the approach I took to tackle this challenge and how it can be applied to any new domain:

Step 1: Adopt the Right Mindset

Sometimes convincing yourself that you can do something is the hardest part and here the impostor syndrome kicks in quite hard. First, don't be afraid to say 'I don't know how to do it', but dont forget to continue with 'but I'll figure it out'. Nobody expects you to know something about its clear that is beyond your expertise. But they do expect you to be willing to learn and figure things out. For this mindset is the key.

The first crucial step is to cultivate an open mindset towards accepting your limited knowledge and learning new, unrelated things. Recognize that the real world demands a diverse skill set, and adaptability is a valuable trait. Embrace the fact that the boundaries of your expertise can be expanded, and be willing to step out of your comfort zone. Embracing a learning mindset will help you approach new challenges with enthusiasm and determination. There's no point on delaying the inevitable, so it's better to start as soon as possible and you'd better have a positive attitude towards it.

Step 2: Start with the Basics

When faced with a new domain, start by gaining a fundamental understanding of the subject matter. Begin with beginner-level resources such as online tutorials, coding platforms, or video lectures. There are a ton of resources for beginners -most of them free- like Codecademy, Udemy, Coursera, Freecodecamp that provide interactive courses that can guide you through the basics of various languages and frameworks. By leveraging your existing knowledge in other frameworks/languages, you can grasp new concepts more quickly and efficiently than a complete beginner and it will allow to focus your energy on understanding the specific language features. Remember, don't try to rush to the advanced topics, you'll get there eventually and you'd better have a solid foundation.

As you learn, expect to make novice errors and encounter challenges along the way. It's essential to persevere and keep learning from your mistakes. Take the time to grasp the specific features and nuances of the new language or framework, going over them repeatedly until you gain a solid understanding. While it's always good to ask questions, try to find answers on your own first. The process of self-discovery fosters deeper learning and better retention.

Step 3: Create a Proof of Concept (POC)

Once you have a foundational understanding of the new domain, it's time to apply your knowledge practically. Seek guidance from your team to understand where your implementation might fit into the existing codebase. By asking questions and seeking clarification, you can get a clearer picture of how your solution should be integrated and what possible experiments you can do to test your ideas.

To gain confidence and experience, start by creating a Proof of Concept (POC) in a separate project. This POC should mimic the structure and functionality of the actual codebase, but in a minimalistic manner. By doing this, you can experiment and test your ideas without the pressure of working directly on the production code. Create as many POCs as you need, they don't even have to resemble the actual codebase, as long as they help you to understand and practice specifics of your future implementation. Remember, what matters in this stage is to prove a solution that works, not how it looks. Don't get yourself distracted with other dependencies, concepts, or patterns that are not related to your solution. The(se) POC(s) will serve as a valuable learning tool and help you understand the practical implementation of your solution and will also bring you confidence in this new domain.

Step 4: Hands-on Actual Implementation

With the POC as your guide, it's time to transition into the actual implementation. Begin with a simple task, even if it's just a print statement. The goal at this stage is to get something working, no matter how basic. By starting with a simple task, you can gain confidence and momentum and will confirm that you're on the right track. Then gradually build upon your initial implementation, adding more functionality and complexity as you go. Aim for incremental progress, steadily improving your solution.

Throughout this process, remember that code quality and abstraction can be refined later. Focus on getting a functional implementation first, and don't be overly concerned with clean code and other good practices, make it work, and once it does, you can take time on making your code better. Commit your code frequently to version control, allowing you to track your progress and revert changes if necessary. I made this blog post of how in order to create great code, you must write ugly code that works first.

Step 5: Seek Feedback

Once you have a working implementation, seek feedback from experienced colleagues on your team. Be open about your newness to the domain and express your willingness to learn. Also, don't expect that your colleague will do the work for you, while they might help your with some specific questions, you should rely on them only for guidance, not for implementation. That should be enough for you to keep improving your implementation. The reviews can and should be iterative, you're most likely not going to get it right the first time, so don't be afraid to ask for feedback multiple times.
Sharing your progress and seeking guidance can help you identify areas for improvement, rectify any mistakes early on, and streamline your codebase. Leveraging the expertise of others can save you time and prevent headaches down the line.

Step 6: Celebrate Your Success

There's nothing more rewarding than overcoming a —probably quite tough— challenge and learning in the process. And believe me, you will learn a lot. You should be proud of your achievement, and hopefully your team will acknowledge all the effort placed on this new challenge.

Congratulations! You now have a new highlight on your professional career and who knows, this may take you to new and exciting opportunities that you'd never thought of before.

Believe me, next time the process will be easier.

Conclusion:

Embracing new challenges outside your comfort zone is an essential part of professional growth. The steps outlined above have helped me to get past the initial hurdles and embrace new challenges with the confidence that they can be overcome with the right strategies and mindset. Remember, learning is a continuous journey, and every new experience expands your skill set. So embrace any possible opportunity to learn about anything new, and watch as your career blossoms with newfound versatility.

Photo from Markus Spiske at Unsplash

How to future-proof your career: stop obsessing over your stack and start widening your professional range

Fernando González Tostado — Tue, 11 Apr 2023 22:18:04 +0000

Since we were young, we've been told to focus, be persistent in life, and not try to chase several objectives at once. We've been taught that if we focus on one single goal at a time, we'll be successful in life.

As developers, we are also told that we should first stick to a technology stack and master it before learning anything else. We keep trying to get better and better until we can build very complex apps and solve complex algorithms.

Myth of Single-Minded Focus

You might have heard of prodigies like Tiger Woods, the Laszlo Polgar kids, Mozart, and others who started their careers from a very young age and spent immense amounts (see the 10,000 hours rule) of time to become the greatest in their trade of all time, all with razor focus on one single objective.

While being perseverant, disciplined, and focused is required to achieve success, it's important to remember that as developers most of us are not athletes, musicians, or scientists, therefore our career efforts should be applied a bit differently. I believe that we are people who enjoy building and making others' lives easier with software, and to build great software products that impact many people usually requires a wide range of technologies and professionals working together.

Before, I would have never thought to stray from my main stack, thinking that I was detouring from my career path and wasting precious time that could have been spent getting better in my stack and any proposal for working in something slightly different would bother me and I'd do only what was only necessary to get the work done. However, recently I've been thinking that it's not worth achieving mastery in a very specific technology anymore in software development. This sudden change of mindset was caused by one big disruption, commercial AI tools.

The Changing Landscape of Software Development

With the disruption of tools like ChatGPT, Github Copilot, and many other AI-powered tools that are now very accessible to anyone, any knowledge, not only technical, is now within reach to anyone. There are many stories of regular people building complex apps or solving complex algorithms with only a few prompts. This means that those skills that were only available to senior developers are much more accessible to anyone who has enough context to command AI with the right prompts.

Don't get me wrong - while being able to solve complex algorithms and understand several complex concepts will still be required in some software positions, and the world will also require those outliers to keep improving it, most of us developers will only be required to be proficient in some base stack, and then have the willingness and mindset to accept that we can acquire knowledge in other concepts that were originally not in our career path at the beginning.

I've seen headlines in social media about prompt engineer positions with a salary range of ~300,000 dollars.

I've seen headlines in social media about prompt engineer positions with a salary range of ~300,000 dollars. While these ranges are, in my opinion, not representative of all the job openings for prompt engineers, the trend I see coming is one where companies will not be searching anymore for the best software developers in X or Y stack. Knowing the productivity boost that AI will bring, what companies will be looking for in any software developer is someone with a wide range of knowledge, rather than an expert in some technology, who should have enough context to connect the dots that connect several technologies within a variety of microservices and apps.

Building Bridges and Connections: The Human Edge

We can't compete against AI. Machines will always be better at doing one single thing. That's a fact, and that's what has fed the interest in keep improving the compute power and respecting Moore's Law. The edge that we have over computers is the fact that we have a wider context than any machine, that we interact, create bridges among other humans, and we adapt to change. These traits should become our weapons, and we must be very aware of them, regardless of the size of our company or even if we are an entrepreneur.

Think of AI as a massive boost to your productivity, not an enemy that will steal your job. Remember all those silly bugs that used to take so long to be fixed? Those unanswered "silly" or niche questions in forums and rude answers mocking us for "not researching enough first"? That repetitive code snippet that just required a few adaptations for your new project? Those times are mostly gone. Actually, there is no better time to be a software developer. With AI, those issues have mostly been solved, so instead of spending your most valuable resource in life - your time - in them, now you can focus your energies on building what no other machine can, which is creating bridges and connections. I now understand what developers from the past felt when they were introduced to Google, or StackOverflow, completely game changers. What a great time to be a developer having the right mindset.

In the words of American philosopher William James:

The greatest discovery of my generation is that a human being can alter his life by altering his attitudes.

Conclusion

Software development as a career is not dying. In fact, it is quite the opposite. The job openings for software developers are still increasing year by year, and the salaries are becoming more and more competitive. What this means is that the role of the software developer is changing, and we need to adapt accordingly. We need to embrace the power of AI and use it to our advantage. With AI doing the heavy lifting, we can spend more time on creative and innovative tasks, building applications that are intuitive and user-friendly. We can focus on solving complex business problems, improving user experience, and making a difference in the world. The future of software development is bright, and it's up to us to seize the opportunities that AI presents us with and keep learning and growing to stay relevant in the industry.

And to be consistent with what I preach, I used AI to help me write this blog post. I wrote the draft without worrying about grammatical, lexical, or contextual errors, and I got some help from it to do what, for me, is the heavy lifting when writing, so I could focus my time on what really matters: sharing my ideas.

Photo from Zach Vessels at Unsplash

The Art of Writing Ugly Code That Works, Then Beautifying It for Optimal Functionality

Fernando González Tostado — Sat, 04 Feb 2023 21:40:50 +0000

Introduction:

When I was starting my career as a developer I usually wrote ugly code — I didn't know it was ugly at the time, but it was. I was so focused on getting the job and I didn't take the time —or even know how- to make my code readable, maintainable, and scalable. As a result, I spent a lot of time debugging and fixing bugs. I also had a hard time explaining my code to other developers. This was a frustrating experience that I didn't want to repeat.

Once I started learning about software development best practices such as the SOLID principles, Atomic Design, abstraction and design patterns my first instinct when writing any piece of new code was to write beautiful code from the very beginning. I wanted to make sure that my code was readable, maintainable, and scalable. However, I quickly realized that this approach was not only time-consuming but also led to frustration. I was spending too much time trying to make my code look perfect, and not enough time focusing on getting the job done. This got worse when I started working on larger projects with more complex code and TypeScript, where typing can be a bit tedious for reusable components.

So I thought, what if I start writing ugly code that initially works and then refactor it to make it more readable, maintainable, and scalable?

"Write Ugly Code That Works": The Benefits

Many software developers make the mistake of trying to write perfect code from the start. However, this approach can be time-consuming and often leads to frustration. By writing ugly code that works, you can focus on getting the job done quickly and efficiently. This allows you to test your ideas and make changes quickly without having to worry about making your code look perfect.

Some of the benefits of writing ugly code that works include:

Faster time to market
Increased productivity
Reduced frustration
More time to focus on testing and debugging

Here's a simple example of a form that works, but is ugly:

Why it is ugly?

If the elements inside it are not reusable.
If the form grows larger and more complex, it will be difficult to maintain and read.
We'd have to copy all the tailwind classes to each element that you'd want to use elsewhere.

// an ugly form
import React from "react";

const UglyForm = () => {
  const [value, setValue] = React.useState("");

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  return (
    <form>
      <input type="text p-4 border border-gray-400 rounded w-64" value={value} onChange={handleChange} />
      <button type="submit p-4 bg-blue-500 text-white rounded hover:bg-blue-600">Submit</button>
    </form>
  );
};

export default UglyForm;

Our first instinct as a seasoned would be to start writing first the reusable components and then the form. But that would bring us the problems earlier mentioned. That's why we wrote ugly code first!

So this is just half of the process, now that it works, we can start beautifying it.

"Beautifying Your Code for Optimal Functionality"

Once your ugly code works, it's time to start beautifying it. This process involves making your code more readable, maintainable, and scalable. By doing this, you can ensure that your code is optimized for performance and efficiency. Some of the steps you can take to beautify your code include:

Refactoring your code to make it more readable and understandable
Adding comments to explain complex parts of your code
Using descriptive variable names
Implementing design patterns to make your code more maintainable
Cleaning up unused or redundant code

import React from "react";

interface Props {
  handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
  value: string;
}

// src/components/atoms/Input.tsx
export const Input: React.FC<Props> = ({ handleChange, value }) => {
  return (
    <input
      className="p-4 border border-gray-400 rounded w-64"
      type="text"
      value={value}
      onChange={handleChange}
    />
  );
};

// src/components/atoms/Button.tsx
const Button: React.FC = () => {
  return (
    <button
      className="p-4 bg-blue-500 text-white rounded hover:bg-blue-600"
      type="submit"
    >
      Submit
    </button>
  );
};

// src/components/molecules/Form.tsx
const Form: React.FC = () => {
  const [value, setValue] = React.useState("");

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  return (
    <form className="p-10">
      <Input handleChange={handleChange} value={value} />
      <Button />
    </form>
  );
};

export default Form;

We now have three reusable components that we can use in other parts of our application, we can easily modify them as needed as our application grows, they also comply with the Atomic Design principles and two of the SOLID principles:

Single responsibility principle: Each component has a single responsibility, the Input component is responsible for rendering an input element, the Button component is responsible for rendering a button element, and the Form component is responsible for rendering a form element.
Open/closed principle: Each component is open for extension but closed for modification. This means that we can easily extend the functionality of each component without having to modify the existing code.

Following this strategy we got rid of frustration, time-consuming bugs, and we can now focus on what's next, testing and debugging. So the next time you're working on a project, remember to write ugly code that works, then beautiful code that also works.

Conclusion:
In conclusion, writing ugly code that works, then beautiful code that also works is an effective approach for software developers. This approach saves time and results in cleaner, more efficient code in the long run. By focusing on functionality first, and then optimizing for readability and maintainability, you can ensure that your code is optimized for performance and efficiency. So the next time you're working on a project, remember to write ugly code that works, then beautiful code that also works.

Photo from Ralph (Ravi) Kayden at Unsplash

How using Tailwind enhances your coding skills

Fernando González Tostado — Tue, 24 Jan 2023 22:52:28 +0000

Recently, there has been a lot of debate among developers in social media about the effectiveness of Tailwind in improving developer experience (DX) when styling components. Some argue that it is just inline styling using classes, and that it can clutter your HTML markup with long class names.

Ok, enough memes. Let's get serious.

Personally, I have used Tailwind in my recent personal projects. My initial experience was mixed. I found that I was repeating styling for many elements and my coding speed was slower due to the unfamiliarity with the naming conventions. I often found myself needing to look up basic selectors for margins, padding, and widths.

A simple styled button would end up like this, with a very verbose className.

<button
 className="absolute top-0 bottom-0 -right-14
     flex items-center justify-center border-0 p-0 text-center
     hover:no-underline hover:outline-none focus:no-underline focus:outline-none"
 type="button"
/>

Using BEM and scss this button would look like this:

<button className="carousel__control--next"/>

Obviously the carousel__control–next class won't add any style by itself. I had to have that selector somewhere in my source:

// somewhere in my scss
// src/styles/components/_carousel.scss


.carousel__control--next {
 top: 0;
 bottom: 0;
 right: -14px;
 border: 0;
 padding: 0;
 text-align: center;
 &:hover {
   text-decoration: none;
   outline: none;
 }
 &:focus {
   text-decoration: none;
   outline: none;
 }
}

I found that using Tailwind did not save me lines of code, but rather added them directly to my elements. Although I was starting to remember the most commonly used class names, it did not improve my developer experience as it only eliminated the need for .scss files.

I was accustomed to separating styling into a separate directory, following an atomic design approach, which made my code appear cleaner and helped me organize my components and their respective styles.

In conclusion, I did not see a significant reduction in lines of code when using Tailwind, but I believed that the real benefit of using it would be the ability to memorize the most frequently used classes. This would help me add extra details to my components and make them look more polished. For example:

// using Tailwind and BEM
<button className="carousel__control--next mx-auto my-12 md:my-4 w-full md:w-1/2"/>

Wow, that's the best of both worlds, isn't it?!

NO, I was completely missing the big picture.

While you can mix selectors and tailwind classname, or add Tailwind classnames to your selectors using @apply in your files to write mixed CSS:

.carousel__control--next {
 // the rest of the styles
 @apply mx-auto my-12 md:my-4 w-full md:w-1/2;
}

It is not really meant to be used for removing HTML markup from your elements, but for overriding styles from a third party library. For example, this Menu.Item component from Semantic UI React:

// overriding a semantic ui button
import { Menu } from 'semantic-ui-react';


<Menu.Item />


// overriding the Item styles with tailwind


.ui.secondary.pointing.menu .item {
 @apply mx-auto my-12 md:my-4 w-full md:w-1/2;
}

In using Tailwind, the benefit is not just in saving lines of code, but also in not having to spend time thinking about class names and jumping between files. By focusing on reusability, which is closely tied to important coding best practices, Tailwind can help enhance our coding skills.

How does Tailwind could actually push us to improve my coding skills?

Have you heard of the SOLID principles? It is basically a set of rules that should help us to make our code more functional, maintainable and robust.

What do SOLID principles have to do with Tailwind?

Both strive for reusability and separation of concerns.

*SOLID and Tailwind
*

Let's start with the first and most important SOLID principle: the Single Responsibility Principle, which encourages us as developers to write components that do only one thing.

Let's say we have a button component, we intend that button to be used for firing the onClick event, or if it's a form button, a submit event, etc:

// a button that accepts onClick, className, type and children props


const Button = ({ onClick, className, type, children, ...props }) => (
 <button
   onClick={onClick}
   className={className}
   type={type}
   {...props}
 >
   {children}
 </button>
);

Now, let's say that we want this button to be our main button for our app. Here's where Tailwind comes in.

const Button = ({ onClick, className, type, children, ...props }) => (
 <button
   onClick={onClick}
   className={`mx-auto my-12 md:my-4 py-2 px-4
   w-full md:w-1/2 bg-blue-500 font-bold text-white
   flex items-center justify-center rounded
   hover:bg-secondary-blue hover:no-underline hover:outline-none focus:no-underline focus:outline-none
   ${className}`}
   type={type}
   {...props}
 >
   {children}
 </button>
);

We now add the fixed classes and accept a className prop, for adapting our button for the specific needs, saving us a lot of lines of code. Also, if we would need to update the styling of the button, we could safely do it, without fear of breaking other components in the way, which is something that could easily happen if we were updating the css file names directly.

By creating a reusable Button component, we might be also forced to think of making use of the atomic design folder structure, where we group our components from generic to specific.

src
├── components
│   ├── atoms
│   │   ├── button.tsx
│   │   ├── link.tsx
│   │   ├── index.ts
│   │   └── ...
│   ├── molecules
│   │   ├── index.ts
│   │   └── ...
│   ├── organisms
│   │   ├── index.ts
│   │   └── ...
│   ├── templates
│   │   ├── index.ts
│   │   └── ...

And When using atomic design we indirectly strive for the Open/Closed Principle, where now that we have smaller items, we can use them as part of a bigger one.

For example, in this Page component:

// this a page component
import { Container, Header } from 'src/components/atoms'
import { ProductSearchbar } from 'src/components/molecules'
import { Table } from 'sr/components/organisms'


return (
 <Container className='text-center'>
   <Header className='3xl'>Hello!</Header>
   <Header className='xl'>I'm a page component</Header>
   <ProductSearchbar className='w-1/2 md:w-1/3 mx-auto' />
   <Table data={tableItems} className='w-full' />
 </Container>
)

Finally, the third SOLID principle involved: the Dependency Inversion Principle, which basically tells us that the components should not care of the implementation details, a higher in the tree level component should handle that:

import { Button } from 'src/components/atoms'
import { Container } from 'src/components/atoms'
import { SomeComponentThatUsesData } from 'src/components/organisms'


export const SomeComponentWithButtons = () => {
 const [data, setData] = useState(null);


 const handleFetchData = async () => {
   // fetch data
   const res = await fetch('https://jsonplaceholder.typicode.com/todos/1');
   const data = await res.json();
   setData(data);
 }


 const handleDeleteData = () => {
   // delete data
   setData(null);
 }


 return (
   <Container className='my-2 md:my-12 w-full md:w-1/2'>
     <Button onClick={handleFetchData} className='bg-blue-500'>Fetch data</Button>
     <Button onClick={handleDeleteData} className='bg-red-500'>Delete data</Button>
     <SomeComponentThatUsesData data={data} />
   </Container>
 )
}

The SomeComponentWithButtons is a component that handles some data in state, that data is then passed to SomeComponentThatUsesData.

As you can see, the buttons don't care about the implementation details, they just know that they receive an onClick prop that is triggered when they are clicked. Whatever is done —and how— it's irrelevant for the button.

The same goes for the SomeComponentThatUsesData component. It can be reused in several other parts of our code without caring how the data received is obtained, while the data is of the type that it requires.

Conclusion

Tailwind is a powerful tool that can greatly enhance your coding skills if you fully embrace and adhere to its core principles. Its emphasis on reusable elements not only promotes clean, maintainable code but also can help enforce SOLID principles without you even realizing it.

However, the ultimate level of power that Tailwind can bring to your development process ultimately depends on your willingness to fully utilize and commit to its recommended practices.

While I have only touched on the basics of the SOLID principles, they can be as complex as you want to make them. By integrating them with Tailwind, you have a great opportunity to fully understand and implement them in your development process. Understanding and utilizing SOLID principles can greatly advance your career as a developer.

Sources

IndexedDB, your offline and serverless DB in your browser with React

Fernando González Tostado — Fri, 13 Jan 2023 20:23:29 +0000

Some months ago I stumbled with this inherited new app in my company.

This app had some awesome and impressive features where I learned —and struggled ☠️— a ton of features that I didn't understand very well —or haven't heard of at all!

One of these cool features was using an IndexedDB for storage.

Honestly it took some time to understand where the hell the data was being stored. I thought that it was fetched everytime or cached with some sort of server magic that was beyond my reach. However, after diving deeper in the code I discovered 💡 that it was using an indexedDB to store the data in the browser, therefore saving a lot of unnecessary requests.

So what's an Indexed DB?

"IndexedDB is a low-level API for client-side storage of significant amounts of structured data, including files/blobs."

Key Concepts

Asynchronous, therefore it won't block your main thread operations ⚡.
A noSQL database, which makes it very flexible —and dangerous ☢️.
Lets you access data offline.
Can store a large amount of data (more than other web storage like localStorage or sessionStorage).

Okay, so once I had a better idea of what an IndexedDB was, I wanted to practice a bit with a simple implementation instead of having to painfully try it with the super complex codebase of my inherited real life application.

Implementation in a React App

This is a low-level API, therefore its implementation is kind of weird, but don't be scared, after some practice everything falls into its place. While there are some third app libraries to handle it —like Dexie—I wanted to try the raw API.

All the methods used here will return a Promise, this way we'll be able to get a response in our component of what's happening in the DB. If you wish, you don't have to wait for a promise to be resolved, it's fine and actually how you'll see the implementation in most pages out there. I like the promise approach for better understanding what's going on 👀 but this approach of course will block the main thread until the promise is resolved.

Initializing the DB

First step, declare the db and open (or init) it in the user browser

// db.ts

let request: IDBOpenDBRequest;
let db: IDBDatabase;
let version = 1;

export interface User {
  id: string;
  name: string;
  email: string;
}

export enum Stores {
  Users = 'users',
}

export const initDB = (): Promise<boolean> => {
  return new Promise((resolve) => {
    // open the connection
    request = indexedDB.open('myDB');

    request.onupgradeneeded = () => {
      db = request.result;

      // if the data object store doesn't exist, create it
      if (!db.objectStoreNames.contains(Stores.Users)) {
        console.log('Creating users store');
        db.createObjectStore(Stores.Users, { keyPath: 'id' });
      }
      // no need to resolve here
    };

    request.onsuccess = () => {
      db = request.result;
      version = db.version;
      console.log('request.onsuccess - initDB', version);
      resolve(true);
    };

    request.onerror = () => {
      resolve(false);
    };
  });
};

This initDB method will basically open the connection myDB —we can have several DB's and this is the tag that identifies them— and then we'll attach two listeners to request.

The onupgradeneeded listener will only be fired when a) we create a new DB b) we update the version of the new connection with for example indexedDB.opn('myDB', version + 1).

The onsuccess listener will be fired if nothing went wrong. Here's where we will usually resolve our promise.
The onerror is self explanatory. If our methods are correct we'll rarely hear from this listener. However, while building our app it will be very useful.

Now, our component will show this super simple UI

import { useState } from 'react';
import { initDB } from '../lib/db';

export default function Home() {
  const [isDBReady, setIsDBReady] = useState<boolean>(false);

  const handleInitDB = async () => {
    const status = await initDB();
    setIsDBReady(status);
  };

  return (
    <main style={{ textAlign: 'center', marginTop: '3rem' }}>
      <h1>IndexedDB</h1>
      {!isDBReady ? (
        <button onClick={handleInitDB}>Init DB</button>
      ) : (
        <h2>DB is ready</h2>
      )}
    </main>
  );
}

If we call the handleInitDB the DB will be created and we'll be able to see it in our dev tools/application/IndexedDB tab:

Hooray! We have the DB up and running. The DB will persist even if the user refreshes or loses her connection 🔥.

Btw, the styling is up to you 😂.

Adding data

For the moment we have an empty DB. We are now going to add data to it.

export const addData = <T>(storeName: string, data: T): Promise<T|string|null> => {
  return new Promise((resolve) => {
    request = indexedDB.open('myDB', version);

    request.onsuccess = () => {
      console.log('request.onsuccess - addData', data);
      db = request.result;
      const tx = db.transaction(storeName, 'readwrite');
      const store = tx.objectStore(storeName);
      store.add(data);
      resolve(data);
    };

    request.onerror = () => {
      const error = request.error?.message
      if (error) {
        resolve(error);
      } else {
        resolve('Unknown error');
      }
    };
  });
};

What's new here?

No onupgradeneeded anymore. We don't make changes to the store version, therefore this listener is not required.

However, the onsuccess listener changes. This time we'll write on the db using the transaction method, which will lead us to be able to make use of the add method, where we are finally passing our user data.

Here Typescript helps us to avoid mistakes when passing our data and keeping our DB integrity intact by accepting a <T> generic type, which for this case will be the User interface.

Finally, in our onerror I didn't want to lose much time for this, it will resolve a string, but it could be an Exception or something similar.

In our component we'll add this simple form to add users.

// Home component
  const handleAddUser = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const target = e.target as typeof e.target & {
      name: { value: string };
      email: { value: string };
    };

    const name = target.name.value;
    const email = target.email.value;
    // we must pass an Id since it's our primary key declared in our createObjectStoreMethod  { keyPath: 'id' }
    const id = Date.now();

    if (name.trim() === '' || email.trim() === '') {
      alert('Please enter a valid name and email');
      return;
    }

    try {
      const res = await addData(Stores.Users, { name, email, id });
    } catch (err: unknown) {
      if (err instanceof Error) {
        setError(err.message);
      } else {
        setError('Something went wrong');
      }
    }
  };

// ...

{!isDBReady ? (
  <button onClick={handleInitDB}>Init DB</button>
) : (
  <>
    <h2>DB is ready</h2>
    {/* add user form */}
    <form onSubmit={handleAddUser}>
      <input type="text" name="name" placeholder="Name" />
      <input type="email" name="email" placeholder="Email" />
      <button type="submit">Add User</button>
    </form>
    {error && <p style={{ color: 'red' }}>{error}</p>}
  </>
)}

If we add the user and go to our application (don't forget to refresh the database for the stale data) we'll see our latest input available in our IDB.

Retrieving data

Ok, we are almost there.

Now we'll get the store data so we can display it. Let's declare a method to get all the data from our chosen store.

export const getStoreData = <T>(storeName: Stores): Promise<T[]> => {
  return new Promise((resolve) => {
    request = indexedDB.open('myDB');

    request.onsuccess = () => {
      console.log('request.onsuccess - getAllData');
      db = request.result;
      const tx = db.transaction(storeName, 'readonly');
      const store = tx.objectStore(storeName);
      const res = store.getAll();
      res.onsuccess = () => {
        resolve(res.result);
      };
    };
  });
};

And in our jsx component

// ourComponent.tsx
const [users, setUsers] = useState<User[]|[]>([]);

// declare this async method
const handleGetUsers = async () => {
  const users = await getStoreData<User>(Stores.Users);
  setUsers(users);
};

// jsx
return (
  // ... rest
  {users.length > 0 && (
  <table>
    <thead>
      <tr>
        <th>Name</th>
        <th>Email</th>
        <th>ID</th>
      </tr>
    </thead>
    <tbody>
      {users.map((user) => (
        <tr key={user.id}>
          <td>{user.name}</td>
          <td>{user.email}</td>
          <td>{user.id}</td>
        </tr>
      ))}
    </tbody>
  </table>
  )}
  // rest
)

And et voilà! We see our data in the table and this data will persist in the browser 👏.

Finally, to make this more dynamic we can make any of theses processes without all these buttons since we receive promises:

  const handleAddUser = async (e: React.FormEvent<HTMLFormElement>) => {
    // ...
    try {
      const res = await addData(Stores.Users, { name, email, id });
      // refetch users after creating data
      handleGetUsers();
    } catch (err: unknown) {
      if (err instanceof Error) {
        setError(err.message);
      } else {
        setError('Something went wrong');
      }
    }
  };

Deleting rows

Finally, we'll understand how to delete data from the DB. This is quite easy, however, we'll have to have in mind which is our Key Path —a.k.a. Unique identifier or Primary Key— for the entries of the selected store. In this case we declared that the id will be that identifier

// db.ts/initDb
db.createObjectStore(Stores.Users, { keyPath: 'id' });

You can also verify it directly by inspecting your store in the dev tools

For more advanced keys you can make use of other Key Paths, however we won't cover those cases here, so using the id as KP is the expected pick.

The method to delete the selected row will accept a storeName ('users' in this case), and the id as parameters.

export const deleteData = (storeName: string, key: string): Promise<boolean> => {
  return new Promise((resolve) => {
    // again open the connection
    request = indexedDB.open('myDB', version);

    request.onsuccess = () => {
      console.log('request.onsuccess - deleteData', key);
      db = request.result;
      const tx = db.transaction(storeName, 'readwrite');
      const store = tx.objectStore(storeName);
      const res = store.delete(key);

      // add listeners that will resolve the Promise
      res.onsuccess = () => {
        resolve(true);
      };
      res.onerror = () => {
        resolve(false);
      }
    };
  });
};

Promises should always be handled with a try/catch block.

And in the component a handler to remove users, and of course a button to pick the desired element in the table

  const handleRemoveUser = async (id: string) => {
    try {
      await deleteData(Stores.Users, 'foo');
      // refetch users after deleting data
      handleGetUsers();
    } catch (err: unknown) {
      if (err instanceof Error) {
        setError(err.message);
      } else {
        setError('Something went wrong deleting the user');
      }
    }
  };

  // ...

  return (
    // ...
    {users.length > 0 && (
      <table>
        <thead>
          <tr>
            <th>Name</th>
            <th>Email</th>
            <th>ID</th>
            // header
            <th>Actions</th>
          </tr>
        </thead>
        <tbody>
          {users.map((user) => (
            <tr key={user.id}>
              <td>{user.name}</td>
              <td>{user.email}</td>
              <td>{user.id}</td>
              // here the button
              <td>
                <button onClick={() => handleRemoveUser(user.id)}>Delete</button>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    )}
  );
}

And the element should be gone after clicking the Delete button 🪄.

Conclusion

To be honest, I think that this API is weird and it feels a lack of implementation examples (for React at least) and documentation —besides a few great ones of course— and it should IMO be used only in a few specific cases. It's always nice to have options, and if it's your case, go ahead, I've witnessed a real production use case in an app that has thousands of users, and I must confess that the IDB has been the feature that has brought me the least trouble. This tool has been out there for several years already, so it's stable enough to be safely used.

If you want to check the full code, here's the repo.

Sources

MDN

Photo from Catgirlmutant on Unsplash

Extra

An interesting approach with promise chaining

Protecting routes with NextAuth in Nextjs

Fernando González Tostado — Wed, 04 Jan 2023 23:16:47 +0000

I've been recently using NextAuth for authenticating users in my projects. NextAuth makes the task super simple and with minimal boilerplate, secure and completely serverless. Love it!

Now that the authentication process is handled with NextAuth, we'll most certainly need to protect some routes, maybe the user details, or any other route that we shouldn't let unauthenticated users access.

While I like protecting routes in Nextjs with its built in middleware, this strategy won't work with NextAuth if you are using database sessions (only with JWT), or if you don't want to over complicate the process, this alternative will be perfect.

Time to get hands on

I expected that you already have your app with NextAuth, if you don't, check this app repository and the docs, it shouldn't take you more than 5 minutes.

The guard wrapper

We'll create a wrapper component that will use the session status with useSession to determine whether the user should be allowed to access, or not.

// components/layouts/protectedLayouts.tsx

import { useSession } from 'next-auth/react';
import { useRouter } from 'next/router';
import { useEffect } from 'react';

type Props = {
  children: React.ReactElement;
};

/*
  add the requireAuth property to the page component
  to protect the page from unauthenticated users
  e.g.:
  OrderDetail.requireAuth = true;
  export default OrderDetail;
 */

export const ProtectedLayout = ({ children }: Props): JSX.Element => {
  const router = useRouter();
  const { status: sessionStatus } = useSession();
  const authorized = sessionStatus === 'authenticated';
  const unAuthorized = sessionStatus === 'unauthenticated';
  const loading = sessionStatus === 'loading';

  useEffect(() => {
    // check if the session is loading or the router is not ready
    if (loading || !router.isReady) return;

    // if the user is not authorized, redirect to the login page
    // with a return url to the current page
    if (unAuthorized) {
      console.log('not authorized');
      router.push({
        pathname: '/',
        query: { returnUrl: router.asPath },
      });
    }
  }, [loading, unAuthorized, sessionStatus, router]);

  // if the user refreshed the page or somehow navigated to the protected page
  if (loading) {
    return <>Loading app...</>;
  }

  // if the user is authorized, render the page
  // otherwise, render nothing while the router redirects him to the login page
  return authorized ? <div>{children}</div> : <></>;
};

This wrapper will allow authenticated users to see its children contents or redirect the user if he's not.

The subscription in the dependency array of the useEffect hook will make sure that we check this logic every time that there's a navigation or session update.

I've also added a loading return statement for the cases where the user reloads or navigates directly to the page so he doesn't get kicked out of the page before being sure about his session status.

The key is that this wrapper will only wrap the components that should be protected. Other components won't be affected by it. How can we make this while not having to manually wrap component by component and thus keeping our code DRYer?

By using the _app.tsx component. Remember that this component runs in every route.

// pages/_app.tsx

// add requireAuth to AppProps
type AppPropsWithAuth = AppProps & {
  Component: {
    requireAuth?: boolean;
  };
};


export default function App({ Component, pageProps }: AppPropsWithAuth) {
  return <SessionProvider session={pageProps.session}>
    {Component.requireAuth ? (
      <ProtectedLayout>
        <Component {...pageProps} />
      </ProtectedLayout>
    ) : (
      <Component {...pageProps} />
    )}
  </SessionProvider>;
}

In the return statement from App by using a ternary the ProtectedLayout component will only wrap on the components where we add the requireAuth property.

I've already updated the AppProps so the component will accept this property and the compiler don't scream at us. If you don't use TS this is not necessary.

The protected components

Now, in any component where we want it to be protected we should add this property with a true value like so:

// pages/protected/index.tsx

import { useSession } from 'next-auth/react';

const ProtectedPage = () => {
  const { data: session } = useSession();
  return (
    <div>
      <h1>Protected Page</h1>
      <p>Hi {session?.user?.name}!</p>
    </div>
  );
};

// add the requireAuth property to the page component
ProtectedPage.requireAuth = true;

export default ProtectedPage;

If we don't add this property, the ternary logic will be false (since .requireAuth is undefined) and the user will be free to navigate to that path regardless of his session status.

Redirecting after authentication

Finally, we'll make use of the redirectUrl query param that it's passed to the redirection route when the user is not authorized.

We'll create a custom login page and override default one from NextAuth.

Our signIn component could be something like this:

// pages/auth/signIn/index.tsx
import { signIn, useSession } from 'next-auth/react';
import Link from 'next/link';
import { useRouter } from 'next/router';
import { useEffect, useState } from 'react';

const SignInPage = () => {
  const [isRedirecting, setIsRedirecting] = useState(false);
  const { data: session } = useSession();
  const router = useRouter();

  useEffect(() => {
    if (session && !isRedirecting && router.isReady) {
      // display some message to the user that he is being redirected
      setIsRedirecting(true);
      setTimeout(() => {
        // redirect to the return url or home page
        router.push(router.query.returnUrl as string || '/' );
      }, 2000);
    }
  }, [session, isRedirecting, router]);

  const handleSignIn = () => {
    signIn('discord');
  };

  return (
    <div>
      <h1>Sign In</h1>
      <p>Sign in to access protected pages</p>
      {session ? (
        <div>
          <p>Currently signed in as {session?.user?.name}</p>
          <p>Redirecting to home page...</p>
          <Link href='/'>
            <button>Go to home</button>
          </Link>
        </div>
      ) : (
        <button onClick={handleSignIn}>Sign In</button>
      )}
    </div>
  );
};

export default SignInPage;

This page will have two uses, the first one, is of course displaying our login providers options to the user.

And second, NextAuth will redirect the user back to this login page, and we'll pick the router.query.returnUrl string and if present, redirect the user to the page that he was trying to access before.

Remember the useEffect from components/layouts/protected.tsx?

Don't forget to update the pathname to our new sign in page — /auth/signIn.

  useEffect(() => {
    // check if the session is loading or the router is not ready
    if (loading || !router.isReady) return;

    // if the user is not authorized, redirect to the login page
    // with a return url to the current page
    if (unAuthorized) {
      console.log('not authorized');
      router.push({
        pathname: '/auth/signIn',
        query: { returnUrl: router.asPath },
      });
    }
  }, [loading, unAuthorized, sessionStatus, router]);

We also must pass the new sign in path to [...nextAuth].ts for the override.

// [...nextauth].ts
export default NextAuth({
  // ...
  pages: {
    signIn: '/auth/signin',  // Displays signin buttons
  },
  // ...
})

And that was it!

If you want to see the full code of the sample app please check the original code.

Sources:

Like react-query and redux? You'll love RTK Query

Fernando González Tostado — Wed, 07 Dec 2022 01:05:16 +0000

React-query —now TanStack Query— is a library that helps you to fetch and manage data in your application. It's perfect for caching and handling data between components and its hooks make your code easy to read and understand.

However, there may be the case where your app uses —or will use— Redux, which IMO is the best option for handling complex state management.

Actually with Redux, you can also fetch and store data in the state using thunks and specifically with ReduxToolKit with createAsyncThunk and handle the thunk promise lifecycle actions in your slice.

Now, supposing that you already have RTK in your app and createAsyncThunk sounds like a lot of boilerplate and you also want a more simpler declarative react-query-type strategy without having to also add react-query in the app?

This is when RTK Query comes into play!

In TanStack Query you would usually fetch declaratively like so:

function App() {
const { isLoading, error, data, isFetching } = useQuery(["repoData"], () =>
 axios
   .get("https://pokeapi.co/api/v2/pokemon/bulbasaur")
   .then((res) => res.data)
 );

We love this declarative way of fetching and caching data!

The great news here is that you can make use of a similar approach with RTK Query.

export default function App() {
 const { data, error, isLoading } = useGetPokemonByNameQuery('bulbasaur')

But where is the inline function and the tag? Well, for that we'll use one single api where tags, requests, invalidations are handled. Why? From the authors:

"Our perspective is that it's much easier to keep track of how requests, cache invalidation, and general app configuration behave when they're all in one central location in comparison to having X number of custom hooks in different files throughout your application."

The aforementhioned api should look like this:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

// services/pokemon.ts
export const pokemonApi = createApi({
 baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
 tagTypes: [],
 endpoints: (builder) => ({
   getPokemonByName: builder.query({
     // name is the actual pokemon name - we used Bulbasaur in the example
     query: (name: string) => `pokemon/${name}`,
   }),
   getPokemonById: builder.query({
     query: (id: number) => `pokemon/${id}`
   }),
   // add more queries in the api
 }),
})

// Export hooks for usage in functional components
export const { useGetPokemonByNameQuery, useGetPokemonByIdQuery } = pokemonApi

As you may have noted, your queries are handled in your api and the hooks are also exported from it. Leaving you to choose where you want to import and use the hook.

I've added a getPokemonById query to the endpoints object to show you that here's where you are going to declare all your queries.

In my opinion this is great, it makes the hooks less verbose and your component code DRYer while still using the pattern that we love from TanStack Query.
As usual in Redux, with great power comes great responsibility which means some initial boilerplate. Just a bit.

You'll only have to add the middleware in your configureStore method and add an entry for the api in your rootReducer:

import { pokemonApi } from './services/pokemon'

const rootReducer = combineReducers({
 [pokemonApi.reducerPath]: pokemonApi.reducer,
})

export const setupStore = (preloadedState?: PreloadedState<RootState>) => {
 return configureStore({
   reducer: rootReducer,
   middleware: (getDefaultMiddleware) =>
     // adding the api middleware enables caching, invalidation, polling and other features of `rtk-query`
     getDefaultMiddleware().concat(pokemonApi.middleware),
   preloadedState,
 })
}

Nothing changes in the way you wrap your app with RTK. So this should be done already

import ReactDOM from 'react-dom/client'
import { Provider } from 'react-redux'

import App from './App'
import { setupStore } from './store'

const store = setupStore()

const reactRoot = ReactDOM.createRoot(
 document.getElementById('root') as HTMLElement
)
reactRoot.render(
 <Provider store={store}>
   <App />
 </Provider>)

Finally, the result will be the exactly same with both strategies:

You can check out both implementations in here.

Bonus - Data Invalidation

And the data invalidation? You've probably used a mutation with useMutation —or even with useQuery— and you want the data to be invalidated after this request and thus the cache removed and the data refetched.

Supposing that we are fetching several posts from the DB. We'd do it this way

export const api = createApi({
 baseQuery: fetchBaseQuery({ baseUrl: '/' }),
 tagTypes: ['Posts'],
 endpoints: (build) => ({
   getPosts: build.query<Post[], void>({
     query: () => 'posts',
     providesTags: ['Posts'],
   }),
   addPost: build.mutation<Post, Partial<Post>>({
     query: (body) => ({
       url: `post`,
       method: 'POST',
       body,
     }),
     invalidatesTags: ['Posts'],
   }),

Adding the tagTypes key with an array of the request tags, that later will be linked with our requests to create a relationship.
Then a providesTags array that accepts a string or a callback. We'll use a string for the moment which would invalidate the entire request.

And in the component where we invoke the mutation:

 // in YourForm.tsx
   const [addPost] = useAddPostMutation()

   const handleAddPost (body) => {
     addPost(body);
   }

   return (
     <form onSubmit={handleAddPost}>
       // your form
     </form>
   )

Once your mutation request has succeeded any other request "linked" with the providesTag: ['Posts'] will have its cache invalidated, hence the data won't be served immediately but it would be refetched to have the data updated.

You can even avoid refetching the entire request by using the providesTag callback similar to how it's done in TanStack Query. If you are interested in a more advanced usage, the docs are very well documented.

Conclusion

Redux might not be the optimal solution for all the apps, most of the time react-query, Zustand, Jotai or —god forbid— even Context are enough for handling and storing states, however, for those who enjoy —or need to use— Redux will not be disappointed with the huge array of tools that RTK provides to the developers to make their experience with Redux frictionless and in my case, enjoyable.

Foto from Oskar Kadaksoo in Unsplash