DEV Community: Hector Leiva

Object Narrowing in Typescript with Graphile Worker

Hector Leiva — Wed, 31 Jan 2024 01:53:57 +0000

I have been using graphile worker for some time for my Matter of Memory project to run async tasks on my Node.js server.

Graphile worker has been great for me because it's a library that works with Postgres that allows me to queue jobs and execute them on the server without adding too many additional layers of complexity for being able to accomplish async tasks. (I'm aware of how popular bull is, but I don't want to add another data-store only for async tasks)

One of the annoying roadblocks I encountered in my implementation of graphile-worker in Typescript was in making sure that whenever I added a task, that the payload I was giving it matched the task name.

Here's an example of the issue I was facing (please note: I'm omitting a lot of set-up code for getting graphile-worker actually working; for that please look at the excellent docs that the graphile-worker team has done.)

Let's say I have 2 background jobs:

Each have different task names
Each have different payloads

// backgroundjobs/tasks/files.ts (terrible name I know)

import { Task } from "graphile-worker";

export interface ConvertFilePayload {
    fileId: string;
    fileType: string;
}

export interface RecordFileMetaDataPayload {
    metaId: string;
}

export const convertFile: Task = async(payload: ConvertFilePayload) => {
    // ...task does work here
}

export const recordMetaDataOfFile: Task = async(payload: RecordFileMetaDataPayload) => {
    // ...task does work here
}

Setup the runner to register these tasks:

// backgroundjobs/index.ts

import { Runner, run, TaskSpec } from "graphile-worker";
import { convertFile, recordMetaDataOfFile } from "../backgroundjobs/tasks/file";
import type { ConvertFilePayload, RecordFileMetaDataPayload } from "../backgroundjobs/tasks/file";

let runner: Runner | undefined;

interface BackgroundJobProps {
    convertFile: ConvertFilePayload;
    recordMetaDataOfFile: RecordFileMetaDataPayload;
}

async function main(connectionString: string) {
    // ...
    runner = await run({
        connectionSTring
        , taskList: {
            convertFile,
            recordMetaDataOfFile
        }
    });
    await runner.promise
}

export async function addJob(
    jobName: keyof BackgroundJobProps,
    options: BackgroundJobProps[keyof BackgroundJobProps],
    spec: TaskSpec = {}
) {
    if (runner) {
        return runner.addJob(jobName, options, spec);
    }
}

export default main;

At this point, we go somewhere else on the server and attempt to add a job for convertFile.

// somewhere/else.ts

import { addJob } from '../backgroundJobs.ts'

backgroundJob.addJob("convertFile", {
    metaId: data.id // this is the wrong payload type, but TS is not erroring out?
});

The problem here is that convertFile doesn't have a payload of metaId, but Typescript sees this as fine because metaId exists as a possible payload option since RecordFileMetaDataPayload is also included in BackgroundJobProps

`convertFile`	`recordMetaDataOfFile`
`{ fileId: string; fileType: string }`	`{ metaId: string }`

Why is this bad? It will make us believe that the convertFile background job is going to work as expected, but we'll end up with a runtime error. The convertFile task will try and pull out fileId from the payload, but it'll be undefined and cause the job to fail.

With TS object narrowing, we can force a TS error whenever the incorrect payload is attempted against the background task we are targeting.

Returning to backgroundjobs/index.ts, we need to modify the Typescript interfaces for the addJob() function to be able to show us the error if we are using the wrong payload.

Previously:

// backgroundjobs/index.ts

export async function addJob(
    jobName: keyof BackgroundJobProps,
    options: BackgroundJobProps[keyof BackgroundJobProps],
    spec: TaskSpec = {}
)

With Object Narrowing:

// backgroundjobs/index.ts

export async function addJob<T extends keyof BackgroundJobProps>(
    jobName: T,
    options: BackgroundJobProps[T],
    spec: TaskSpec = {}
)

How this works:

<T extends keyof BackgroundJobProps> is a way to create a Typescript generic T that will represent one-of-the possible keyof values of BackgroundJobProps. This means (in this case) convertFile | recordMetaDataOfFile
jobName: T is meant to cast whichever string we write as our first argument when we use addJob("") and assign it to T here. We can only pick "convertFile" or "recordMetaDataOfFile" since those are the only keys in BackgroundJobProps. We are going to pick "convertFile" for the next point.
options: BackgroundJobProps[T] since we have cast T by explicitly declaring it in addJob("convertFile") what we've done is narrowed down all values in BackgroundJobProps to only the values that match BackgroundJobProps["convertFile"] and it returns those values for the options as the interface that must be matched.

Now if we attempt to do:

// somewhere/else.ts

import { addJob } from '../backgroundJobs.ts'

backgroundJob.addJob("convertFile", {
    metaId: data.id // this will now error out and show up as a TS Error
});

This will now work as expected and return a TS error.

I had screwed this up myself some time ago which caused an influx of errors that were difficult to find since there were no TS errors being reported, not a fun day at work!

I hope you all find this helpful and learn from my mistakes.

-H

Using Nodejs Buffers to transcribe an Audio file using OpenAI's Whisper service

Hector Leiva — Tue, 01 Aug 2023 00:14:10 +0000

I was having a difficult time attempting to do the following:

Retrieve an Audio file from AWS S3
Have the Audio file in memory be sent to Open AI's Whisper transcription service to get the transcribed text and save the result.

I've seen some examples where users were attempting to use a ReadStream instead and attempt to send that, but that didn't work for me.

So after a Sunday's worth of effort to figure out how to send this data, I did the following (using this specific version of OpenAI's Node.js API: 4.0.0-beta7)

s3.service.ts

function async returnBufferFromS3(params: { key: string }) {
      const data = await this.awsS3.send(new GetObjectCommand({
        Bucket: 'some-bucket'
        , Key: params.key
      }));

      const stream = data.Body as Readable;

      return new Promise<Buffer>((resolve, reject) => {
        const chunks: Buffer[] = [];
        stream.on('data', (chunk) => chunks.push(chunk));
        stream.on('error', (error) => reject(error));
        stream.on('end', () => resolve(Buffer.concat(chunks)));
      });
}

openAITranscription.ts

import { returnBufferFromS3 } from "s3.service";
import { isUploadable } from "openai/uploads";
...

const openAI = new OpenAI({
  apiKey: 'some-api-key',
  organization: 'some-org-id'
});

function async returnTranscriptionsBasedOnKey(key: string) {
      const buffer = await returnBufferFromS3({ key: 'some-key; });
      const tmp = new Blob([buffer], { type: `test.mp4` });
      const fileLikeBlob = return Object.assign(blob, {
          name: 'test.mp4'
          , lastModified: new Date().getTime()
     });

      if (!isUploadable(fileLikeBlob)) {
        throw new Error(`Unable to upload file to OpenAI due to the following not being uploadable: ${fileLikeBlob}`);
      }

      const openAIResponse = await openAI.audio.transcriptions.create({
        file: fileLikeBlob,
        model: 'whisper-1'
      }

      return openAIResponse;
}

This seems like an incredible hacky way of completing this task (Buffer -> Blob -> "FileLikeBlob").

I'm not proud of it, but I didn't enjoy the time I spent trying to make this work either.

If anyone in the comments has better recommendations of how to accomplish this same method; I welcome any critique to make it better and to make this information more readily available to more users.

NightCrit v2.0 (release 1.0)

Hector Leiva — Mon, 06 Feb 2023 13:34:03 +0000

I've completed the first iteration of NightCrit v2.0 in it's current form several days ago:

https://nightcrit.com

There were a number of obstacles that had to be overcome:

How will Unity render the output of my project?

It is important to me that NightCrit is rendered out so that it is available on the web. A VR-only environment was too limiting for what I wanted.

I was looking for releasing this project to the largest audience possible, while still attempting to be as immersive as possible. I looked into WebGL and this seemed like it would be the best approach.

How do I host this Unity WebGL project?

I already had the domain and a S3 bucket set-up for the Vue project that was NightCrit v1.0. I replaced the contents of that project with the output from Unity.

The biggest headache was getting errors on the index.html around the Content-Encoding: not being set correctly. For those that stumble onto this issue in the future (including myself) and are wondering what needs to be updated in order to have .gz data fetched correctly from S3, this is what needs to be accomplished:

The Content-Encoding needs to be set on the S3 bucket object itself.

Future Plans

There are a few other number of things I wanted to accomplish. The most important thing is that the bones of this project seem to be there; and because of that I felt compelled to publish what I had.

There will be further updates in trying to make the models better and adding more atmospheric elements to get the feeling that I had in the dream down.

What's important is to try and show people what I've accomplished thus far.

Thank you for reading.

NightCrit v2.0 (in progress)

Hector Leiva — Tue, 13 Dec 2022 03:31:39 +0000

It's been over a month since I posted about creating a project about a dream I had dubbed "Nightcrit".

Here is an update on what I've currently accomplished:

I've learned how to use Blender to begin to model out the world of Nightcrit
I've started reading and watching tutorials about Unity on how to import the models made in Blender and have a user walk through it.
I've started learning C# in order to program functionality in the world like preventing a user from falling off the map and triggering audio cues.

Blender screenshots:

Unity screenshots:

Some of what remains before I attempt to render this out for the world to see are; the audio messages need to be redone and importing the paintings into the scene.

I tried to import the audio files as they are and placed them more or less where I had them before in the v1.0 and they do not work in a First Person game engine. It doesn't have the correct "feel", so the audio needs to be re-written and recorded again.

I hope to have something close to done around this time next month.

This is my first time using Unity at all and it's been a nice experience so far.

NightCrit v1.0

Hector Leiva — Wed, 09 Nov 2022 02:21:49 +0000

I had a dream on October 23rd, 2020 and I'm trying to make it so that other people can experience the dream.

Nightcrit is becoming another art work that I'm using my technologist skill set to implement.

The first iteration is using Vue.js and basic (i.e. amateur) 3D renderings in order to re-create scenes that fit the feeling of the dream overall.

This has been a great project to learn a bit of Vue and Blender and see how far I can go with Youtube tutorials and a vision.

I've also been diving into the WebAudio API to try and create atmospheric generative soundscapes that fit the dream. I've only implemented a Brown noise generator; but it is effective in capturing the mood that I'm looking for.

There are many other projects that people have created already that are influential:

My next steps are to learn Unity enough to create an artifact that will allow users to open Nightcrit and be able to move themselves through this landscape and trigger the audio events as they move through it.

I will have to re-create the 3D apartment building again to allow a virtual user to walk through it, but I'm looking forward to the challenge.

Github Actions and creating a short SHA hash

Hector Leiva — Fri, 30 Sep 2022 00:49:29 +0000

This will be a quick post as a sort of reminder for myself (and anyone else) on how to actually generate a short git commit SHA hash in Github actions for a particular build.

git commit hashes are important for various reasons

git commit SHA hashes are useful in tagging releases and to know what was the state of the code at a certain point in time.

git commit SHA hashes are also really long: 9c1e1a7f8f3827b11fb9eb34ab0a21afde30e19c (for example). Sometimes as an engineer you just need to know the first say 6 characters and that's more than enough to know which point in time the code is in.

Github provided short commit SHA hashes for some time, but not anymore

Github depreciated the Short SHA environment variable in January, 2021

This makes sense because if you're going to shorten a git commit SHA, which one are your planning on shortening? You might need the github.event.pull_request_head.sha for certain workflows OR you might need the github.sha which depends on which event triggered that specific run.

My solution to generating a short git commit SHA hash

(Edited: as per @eazylaykzy in Oct 14, 2023, you should use the following due to the deprecation of set-output)

- name: Set short git commit SHA
  id: vars
  run: |
    calculatedSha=$(git rev-parse --short ${{ github.sha }})
    echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV

- name: Confirm git commit SHA output
  run: echo ${{ env.COMMIT_SHORT_SHA }}

(deprecated version as of Oct 14, 2023)

# The following is depreciated, left here for historical reference

- name: Set short git commit SHA
  id: vars
  run: |
    calculatedSha=$(git rev-parse --short ${{ github.sha }})
    echo "::set-output name=short_sha::$calculatedSha"

- name: Confirm git commit SHA output
  run: echo ${{ steps.vars.outputs.short_sha }}

How is this different from what's in Stackoverflow

What's annoying about this particular Stackoverflow post is that none of the solutions stated are quite correct as-of the writing of this post.

run: echo "::set-output name=sha_short::$(git rev-parse --short HEAD)"

Doesn't work since you don't know exactly which HEAD is being declared in the context of a Github Action runner.

echo "::set-output name=sha_short::$(git rev-parse --short ${{ github.event.pull_request.head.sha }})"

Doesn't work because you can't use "" double-quotes when referencing ${{ }} tags. But even if you used the '' single-quotes to wrap this expression, what ends up happening is that sha_short doesn't equal the string of the git commit SHA, but it's the expression:

$(git rev-parse --short ${{ github.event.pull_request.head.sha }})

So any time you use sha_short later on in your run, it'll have to re-run that entire expression again (which will return what you want, but there's no need to re-run an expression and instead it's better to store the value).

I hope that this might help anyone else who is trying to find a simple way to shorten a git commit SHA hash. At least for now!

What I believe Web 3.0 could be

Hector Leiva — Wed, 15 Jun 2022 13:11:42 +0000

The designation “Web 3.0” is often used as an umbrella term for Cryptocurrency, NFT markets, and "the block-chain," but I have greater hopes for the Web’s next iteration. Web 3.0, to me, is about building true decentralization. Cryptocurrencies and NFT markets do not live up to being the decentralized havens they proclaim to be, but there are other projects being created now that are the decentralized technologies we need for the future. The Web needs to evolve in order to support users in the inevitable times of crisis brought on by climate change.

The mesh networks in Spain, New York City, and Detroit are examples of a decentralized Web 3.0. These networks begin as hyper-localized communities which function independently of the global network yet are able to access it as we do now.

I emphasize hyper-local community networks such as these because when disaster strikes in the form of black-outs, water displacement, fire emergencies, and food shortages, it is your local community network that will be there to help first. Cryptocurrencies and NFTs break down when they aren't tied to the global network, rendering them useless in times of crisis.

My vision of Web 3.0 includes AI assistants that rely on hardware and the use of edge networks based within a person's home, allowing the AIs to work on behalf of the user without needing to always be connected "on-line". These assistants will never need to connect to a third-party unless explicitly directed by the user.

I imagine a class of devices that are designed to be off-the-grid first and work without ever needing the internet, such as wearable IoT devices that help you learn more about yourself instead of spying on you and reporting to the rest of Silicon Valley.

Creators in the Fediverse are designing software, such as IPFS and Mastodon, that work without needing to be connected to the internet by default.

This Web, which prioritizes local communities over the global network, can free us from relying on Amazon, Google, Apple, etc. and pull us toward each other. It encourages us to have an eye towards conservation of our communities instead of consumerism.

A decentralized Web comes closer every day as more people join Discords as their preferred community environment. Seeking alternatives to Facebook, Instagram, Tiktok, and Twitter, people join Discords because they want fewer hateful messages from anonymous users and more channels of communication to talk with friends about favorite TV shows.

In the end, I hope for a Web that returns power to the users. Building the Web with decentralization as a priority will make us resilient against the perils of the future. We need a Web in which privacy is a foundational property, where apps work for the users again. Instead of making a few companies ultra-wealthy, this Web can become a tool that helps everyone, both in our daily lives and in times of crisis.

How writing state machines made me feel like a programmer

Hector Leiva — Sat, 26 Sep 2020 15:28:58 +0000

I've been working as a "web developer" since 2012.

I am a self-taught programmer who has worked on custom PHP frameworks, Wordpress, Drupal, Node.js apps, and Python microservices.

It wasn't until 2019, when I wrote my first state machine, that I felt like I wrote something as a programmer.

Writing a state machine for work using xstate and knowing that over a year later that code is still in production has given me a greater sense of self-worth.

What are state machines?

Before I get ahead of myself, for anyone who isn't aware, xstate is a Javascript library that implements finite state machines.

Finite state machines are a model of how to describe the world.

A machine exists in a state and transitions are created to show how the machine can move to different states or go back into the same state (a vending machine is a finite state machine).

These definitions at the start didn't do much for me, and they certainly didn't make me feel like a better programmer by "knowing" what they meant. I had to actually create something using these concepts in order to feel like I got it.

UI's have always been complicated

I work in healthcare. Healthcare apps are notorious for having complex UI's and forms that people need to fill out. At my job we use React and Redux.

There was a breaking point in 2019 when we needed to make a new UI flow for providers. My co-worker and I were writing out the following Redux object for the nth time:

{
  didInvalidate: boolean;
  isFetching: boolean;
  hasError: boolean;
}

that we realized that there had to be a better way. This pattern wasn't working for us regardless of how many other posts endorsed it.

Youtube recommended this video on designing state machines for UX:

and I pitched it to my co-worker the day after. He examined the library and he didn't see any issues with it. We pitched the usage of this library to our engineering manager and he approved it as well.

It took us longer to build the feature since the xstate API was new to us; but the end result was a bug-free release.

It wasn't only that using xstate made the release of the feature bug-free, but everything around writing the code that convinced us that this was the way forward to developing UX.

I learned how to ask questions

Finite State Machine models force you as the programmer to clearly state what will happen with the thing you are building.

How does a user get from A -> Z?
Can the user end up in X for any reason?
Are there any ways to catch the user if they are in a state we didn't account for?

I never asked myself these questions before coding. These were problems I addressed as I was writing the React components and using this.state or Redux to figure out. This is backwards.

We (as programmers for the web) should always be using state charts to answer these questions. I had to ask the designer multiple times about specific error states that weren't addressed. I had to direct message the product manager about the user types that weren't accounted for in the initial feature request. It was an ongoing conversation between all of us because we all wanted the feature to succeed.

How I felt like a programmer

We asked questions on what we were building. Once we were experts in the feature that we were about to build, did we then start to write out code.

As we finalized our machine objects and knew precisely what our feature was going to do, it was this confidence in the finite state machine model that made me feel like we "leveled up".

We became programmers because we knew how the thing that we built was going to work.

Start to write plugins for OBS with Lua

Hector Leiva — Thu, 17 Oct 2019 04:32:21 +0000

I often record my D&D sessions with my friends who are all remote via OBS. Open Broadcaster Software (aka OBS) is a: popular, free, and open-source cross-platform streaming and recording program.

I have text that is a timestamp of the day we play D&D on the screen so that whenever we review the footage, we always know from which session it was:

But I didn't want to continue to rewrite the date manually every time.

Sometimes I would forget and the footage would have the incorrect date and it would affect the order of the videos. So I set out to figure out how to write a script in OBS that would set today's date for me.

As a bonus, I wanted to see if I could add a prefix and suffix options to the date as well, just in case I wanted to add additional text before or after the date.

OBS is written in C, C++. But for the purposes of this post is to showcase one of OBS' best features which is that since version 21.0+, anyone can write a script which can use "hooks" that are available in to effectively do anything.

OBS scripting documentation is located here and there are two important notes. You can write your scripts in either Python 3 or Luajit 2 (Lua 5.2) which hook into the C/C++ methods that run OBS.

Despite knowing Python more than Lua; this small task which has a fast iterative cycle seemed like the best time to learn how Lua works.

Figuring out the OBS hooks for writing plugins:

OBS' main hooks are contained in this document but I focused on the following hooks:

script_load
script_update
script_defaults
script_properties

script_load in the "lifecycle" of OBS, is called whenever a new source is created or source is activated. Sources are a collection of inputs (audio/video/moving/static) that map to a specific scene.

script_update is called whenever the user has modified the script that is in use.

script_defaults is called whenever the script is initialized.

script_properties is called to load all the possible options for the script.

Reverse Engineering a Lua Script

I followed a script that comes preloaded with OBS called countdown.lua located within frontend-tools/scripts/ and dissected the following things:

To import the OBS library

obs = obslua

One must set-up global variables

source_name = ""
prefix = ""
suffix = ""

Lua is functional, everything else is a function from here on out. To hook into script_properties, one must make it into a function:

function script_properties()

   ...

end

Specific obs functions must be called to register the source that we are modifying and the options that that would modify the source. Looking at script_properties again, I will showcase the script I wrote for this hook:

obs = obslua

source_name = ""
prefix = ""
suffix = ""

function script_properties()
    local props = obs.obs_properties_create()

    local p = obs.obs_properties_add_list(props, "source", "Text Source", obs.OBS_COMBO_TYPE_EDITABLE, obs.OBS_COMBO_FORMAT_STRING)
    local sources = obs.obs_enum_sources()

    -- As long as the sources are not empty, then
    if sources ~= nil then
        -- iterate over all the sources
        for _, source in ipairs(sources) do
            source_id = obs.obs_source_get_id(source)
            if source_id == "text_gdiplus" or source_id == "text_ft2_source" then
                local name = obs.obs_source_get_name(source)
                obs.obs_property_list_add_string(p, name, name)
            end
        end
    end

    obs.source_list_release(sources)

    obs.obs_properties_add_text(props, "prefix", "Prefix Text", obs.OBS_TEXT_DEFAULT)
    obs.obs_properties_add_text(props, "suffix", "Suffix Text", obs.OBS_TEXT_DEFAULT)

    return props
end

obs.obs_properties_create() is used to create an instance of a props data type that maps to an object in C/C++ for OBS.
Passing props into obs.obs_properties_add_list(props, "source", "Text Source", obs.OBS_COMBO_TYPE_EDITABLE, obs.OBS_COMBO_FORMAT_STRING) creates a dropdown list that has a user-facing Text Source that maps its values to "source".

The loop that starts here:

local sources = obs.obs_enum_sources()

    -- As long as the sources are not empty, then
    if sources ~= nil then
        -- iterate over all the sources
        for _, source in ipairs(sources) do

is called by loading all the sources that the user has, making sure at least one exists, and then iterating over them. I only want to target sources for which the source is a Text source only. That's what is happening here:

for _, source in ipairs(sources) do
            source_id = obs.obs_source_get_id(source)
            if source_id == "text_gdiplus" or source_id == "text_ft2_source" then
                local name = obs.obs_source_get_name(source)
                obs.obs_property_list_add_string(p, name, name)
            end
        end

If the source has an internal id of "text_gdiplus" or "text_ft2_source", we grab the name of that source and modify the properties of the list from earlier and add the name of that source into the dropdown.

Important note, you are still writing in C/C++

Despite the fact that we can write these scripts in Lua or Python, these scripts are linked to the C/C++ internals of OBS and thus follow the same rules of needing to release memory whenever we no longer need the resource.

That means if we do: local sources = obs.obs_enum_sources(), after we are done with messing with the sources, we need to release this from memory by doing the following:

obs.source_list_release(sources)

Just because we are using higher level languages in this script, that doesn't mean we can forget about memory management.

The last part is needing to add an option for the prefix and suffix and have it available as a free-text field for the user to fill in:

    obs.obs_properties_add_text(props, "prefix", "Prefix Text", obs.OBS_TEXT_DEFAULT)
    obs.obs_properties_add_text(props, "suffix", "Suffix Text", obs.OBS_TEXT_DEFAULT)

Once we are done with setting up the configuration for the script, we need to return the props:

return props

The other 3 "hooks" for this implementation can be viewed at my Github page where I've made this code available for anyone else to use:

https://github.com/hectorleiva/obs_current_date