DEV Community: Andy Wermke

Seamless web workers & worker threads - threads.js

Andy Wermke — Sat, 28 Dec 2019 16:19:42 +0000

A quick leap into running cross-platform Javascript / TypeScript code in workers. Using a transparent API – minus the hassle.

After half a year in beta, threads.js v1.0 has finally been released. It allows you to use web workers and worker threads in an intuitive way, provides features like thread pools, works in web clients as well as node.js and is less than 10kB in size!

The benefits of using workers have already been covered in plenty of other articles, so here is the gist:

Leverage all the available CPU power to run heavy CPU-bound tasks
Move all non-rendering code off the main thread to ensure smooth animations and a responsive user interface (web workers)
Isolate software modules, restrict them to communicate via message passing

Now even though the web worker and worker threads APIs are similar, unfortunately they are not fully compatible. Furthermore, they are rather low-level building blocks: Create a worker, subscribe to message, post a message, etc.

What happens if you post some messages to a worker and one causes the worker to throw? Chances are the calling code will never know there was an error - it will just not receive a response message. And then there is all the glue code…

Powers of a transparent API

Enter the stage… threads.js! Let's write a simple worker that hashes passwords for us.

// workers/auth.js
import sha256 from "js-sha256"
import { expose } from "threads/worker"

expose({
  hashPassword(password, salt) {
    return sha256(password + salt)
  }
})

Now let's write the main thread's code – spawn a new worker and hash a password.

// master.js
import { spawn, Thread, Worker } from "threads"

async function main() {
  const auth = await spawn(new Worker("./workers/auth"))
  const hashed = await auth.hashPassword("Super secret password", "1234")

  console.log("Hashed password:", hashed)

  await Thread.terminate(auth)
}

main().catch(console.error)

It's simple. Expose a function in the worker, call it from the other thread – done!

Note that auth.hashPassword() will always return a promise, whether hashPassword originally returns a promise or not – the return value will be promisified, due to the async nature of worker communication.

So what about error handling? It's simple as we are now working with a promise-based API.

// master.js
import { spawn, Thread, Worker } from "threads"

async function main() {
  let auth, hashed

  try {
    auth = await spawn(new Worker("./workers/auth"))
  } catch (error) {
    // Cannot spawn the worker or crashed immediately before doing anything
  }

  try {
    hashed = await auth.hashPassword("Super secret password", "1234")
  } catch (error) {
    // Hashing this password failed
  }

  console.log("Hashed password:", hashed)

  await Thread.terminate(auth)
}

main().catch(console.error)

By the way, did you notice Thread.terminate()? We use it to terminate a worker once we are done using it.

Run in node.js

Let's take our previous sample code and change the ES module import statements into require() calls for now. You can clone the code from this GitHub Gist.

$ git clone git@gist.github.com:925395687f42f6da04d111adf7d428ac.git ./threads-gist
$ cd threads-gist
$ npm install

Running it is trivial.

$ node ./master

This code will run in any node.js version that comes with worker threads support, so node 12+ or node 10+ with a feature flag set.

You can even run it on node 8.12+. Install the tiny-worker npm package – threads.js will automatically pick it up as a polyfill if worker threads are not available.

Build using webpack

A vast number of people use webpack to bundle their code for front-end deployment. So how do we now make that code build with webpack?

We use our code as is, take our webpack config and add the threads-plugin – that's it!

  // webpack.config.js
  const path = require("path")
+ const ThreadsPlugin = require("threads-plugin")

  module.exports = {
    entry: {
      app: "./src/index.js"
    },
    mode: "development",
    module: {
      rules: [
        {
          test: /\.css$/,
          use: ["style-loader", "css-loader"]
        },
        {
          test: /\.jsx?$/,
          use: ["babel-loader"]
        }
      ]
    },
    output: {
      path: path.join(__dirname, "dist")
    },
    plugins: [
      new HtmlPlugin(),
+     new ThreadsPlugin()
    ]
  }

The plugin is based on Google's worker-plugin – it will recognize new Worker() expressions, make sure the referenced worker file is bundled independently from the main entrypoint and rewrite the path in the new Worker() expression to the worker bundle path.

First class TypeScript support

Threads.js is written in TypeScript and thus fully statically typed, so your IDE's IntelliSense will show you all available exports, functions and parameters with documentation as you write. That's not all – even running TypeScript workers becomes easier.

When running your TypeScript code in node.js you will frequently find yourself using ts-node in development and running the transpiled JavaScript code in production.

When resolving a worker, threads.js will try to load the transpiled JavaScript worker. If that fails and ts-node is installed it will automatically fail-over to run the untranspiled TypeScript worker file using ts-node. You don't have to lift a finger 🙌

Thread pools, observables & more

There is more to explore!

Thread pools to spawn multiple workers and dispatch jobs to them
Returning observables to expose events to subscribe to
Support for transferable objects to efficiently pass binary data
and more… 🚀

You can find the detailed documentation on threads.js.org.

There are also more features to come. Check out the GitHub repository and its issues to see what's in discussion right now or watch the repository's releases to stay up to date.

That's it for today – I hope you enjoyed the blog post. If you like the project, give the repository a 🌟 on GitHub, contribute to the development or become a sponsor.

Feel invited to comment and leave feedback of any kind below.

Happy holidays and happy hacking!

Andy

Teaser image by Adi Goldstein on Unsplash.

How to use: npm tags

Andy Wermke — Fri, 25 Jan 2019 16:01:57 +0000

There is a feature in npm that affects every npm install, every npm publish, yet most npm users seem to be unaware of.

Time to talk about npm tags!

What they are

Let's jump right into it:

On every npm install <package> without an explicit version, a tag is used to resolve the right version number: The latest tag.
On every npm publish a tag is either updated or created. Yes, it defaults to the latest tag, too.

So let's assume a busy work day has just begun and you add a new package to your dependencies:

$ npm install cowsay

Now as you did not specify any version to install, how does npm decide which version to use? It uses the latest tag!

Check this out:

$ npm show cowsay

cowsay@1.4.0 | MIT | deps: 4 | versions: 19
cowsay is a configurable talking cow
https://github.com/piuccio/cowsay

keywords: cow, cowsay, cowthink, figlet, talking, ASCII

bin: cowsay, cowthink

(...)

dist-tags:
latest: 1.4.0

published a month ago by piuccio <piuccio@gmail.com>

Have a look at dist-tags. It shows only one tag, the latest tag. Judging by npm show's output we can already imagine what a tag's function is:

Tags are a mapping from some human-friendly identifier to a specific version number.

Aha! So when you do your casual npm install cowsay, npm will fetch the package metadata (try npm show cowsay --json), including a list of all published tags of the package. The latest tag will tell npm what version to install.

So why doesn't npm just install the version with the most recent publishing timestamp? We will get to this in no time, but let's add a spoiler here:

Because the most recent npm publish might not have published a stable version, but maybe some early beta version that the user is not supposed to run in production.

Using tags

Consuming

To install a package, but not the latest tag:

$ npm install <package>@<tag>

A popular example would be:

# Install the latest alpha version of React
$ npm install react@next

Publishing

To publish a version of your precious package that should not be installed by default:

$ npm publish --tag <tag>

This way you can easily share some unstable code with others, so they can test it:

$ npm publish --tag beta

$ npm publish --tag testing-feature-new-dashboard

As already mentioned before, running npm publish without a --tag parameter will also update a tag: The latest tag which is the default tag for publishing and installing.

Changing tags

You can always change tags to point to another version if you need to. Use the npm dist-tag sub-command for that:

$ npm dist-tag --help
npm dist-tag add <pkg>@<version> [<tag>]
npm dist-tag rm <pkg> <tag>
npm dist-tag ls [<pkg>]

alias: dist-tags

Use it to fix the tag if you accidentally published a version using the wrong tag.

Difference to git tags

It's important to note that npm tags are semantically different to how git tags are commonly used, even though technically they are very similar.

A git tag points to a commit, which is the code at a particular point in time, and usually never changes. The git tag is essentially the equivalent of an npm version.

An npm tag on the other hand is a mutable pointer to a version, which in turn is an immutable pointer to the code at one particular point in time. So an npm tag is basically a meta pointer.

When thinking in git terms, both npm tags and npm versions could be implemented using git tags, just that the former type of tag would be considered mutable, while the version git tags would be considered immutable.

Profit $$

So how can we use that feature to our benefit in day-to-day work?

We can:

Share an unstable version with beta testers: npm publish --tag beta
Publish a use-once-and-forget version: npm publish --tag testing-new-feature

Installing that version on the other end will be just as simple:

$ npm install my-fancy-package@testing-new-feature

Release early, release often. Don't screw with your production users, though. Use npm tags.

Happy hacking!

Teaser photo by Paul Murphy on Unsplash. Shows spray tags, not npm tags.

Built an unconventional database thing

Andy Wermke — Wed, 09 Jan 2019 20:02:32 +0000

Hey folks!

I just built a tool to statically evaluate SQL queries in JavaScript and TypeScript code: Postguard.

It's born out of the desire to write explicit database queries without a query builder, yet statically analyzable, and built on top of Babel and the TypeScript compiler API.

What does it do?

You query the database like this:

import { sql } from "squid/pg"
import database from "./database"
import { UserRecord } from "./schema"

export async function queryUserById(id: string): Promise<UserRecord | null> {
  const { rows } = await database.query<UserRecord>(sql`
    SELECT * FROM users WHERE if = ${id}
  `)
  return rows[0] || null
}

Define a schema for your tables. The record type can be derived from the schema when using TypeScript:

// schema.ts
import { defineTable, Schema, TableRow } from "squid"

export type UserRecord = TableRow<typeof usersTable>

const usersTable = defineTable("users", {
  id: Schema.Number,
  name: Schema.String,
  created_at: Schema.Date
})

Now let's run postguard to validate what we just wrote:

$ npx postguard ./sample/*.ts

✖ Query validation failed in sample/test.ts:7:32:

  No table in the query's scope has a column "if".
  Tables in scope: "users"

   5 | export async function queryUserByID(id: number) {
   6 |   const { rows } = await database.query<UserRecord>(sql`
>  7 |     SELECT * FROM users WHERE if = ${id}
     |                               ^
   8 |   `)
   9 |   return rows[0] || null
  10 | }

Ahhh, we have a typo in our query! Let's fix it:

const { rows } = await database.query<UserRecord>(sql`
  SELECT * FROM users WHERE id = ${id}
`)

Let's run it again:

$ npx postguard ./sample/*.ts

✔ Validated 1 queries against 1 table schemas. All fine!

More advanced stuff

Let's take our previous sample code and change the SELECT query:

import { sql } from "squid/pg"
import database from "./database"
import { UserRecord } from "./schema"

export async function queryUserById(id: string): Promise<UserRecord | null> {
  const { rows } = await database.query<UserRecord>(sql`
    SELECT id, name FROM users WHERE id = ${id}
  `)
  return rows[0] || null
}

$ npx postguard ./sample/*.ts

✖ Query validation failed in sample/test.ts:6:40:

  Query's result does not match the expected result type.
    Missing columns in result rows: "created_at"
    Actual columns in result rows: "id", "name"

  4 |
  5 | export async function queryUserByID(id: number) {
> 6 |   const { rows } = await database.query<UserRecord>(sql`
    |                                        ^^^^^^^^^^^^
  7 |     SELECT id, name FROM users WHERE id = ${id}
  8 |   `)
  9 |   return rows[0] || null

What happened? We defined that we expect the query to return rows of type UserRecord:
await database.query<UserRecord>(/*...*/)

Postguard evaluated the query and noticed that the result rows of that SELECT query do not match the TypeScript type UserRecord, since that type has a created_at property.

The fix is trivial:

import { sql } from "squid/pg"
import database from "./database"
import { UserRecord } from "./schema"

export async function queryUserById(id: string): Promise<UserRecord | null> {
  const { rows } = await database.query<UserRecord>(sql`
    SELECT * FROM users WHERE id = ${id}
  `)
  return rows[0] || null
}

$ npx postguard ./sample/*.ts

✔ Validated 1 queries against 1 table schemas. All fine!

Why?

So why did I even spent my time on that? Having worked with ORMs for years, I slowly grew more and more tired of them. A query builder seemed like a better solution.

Now the issue with query builders is that you effectively write SQL queries, but not as SQL queries; you formulate them using the query builder's proprietary API. Now I need to read up on two complex interfaces: My Postgres' fancy SQL features AND the query builder's comprehensive API...

Writing good old SQL feels like the natural way, so back to that. But now I've lost all confidence in my code and need to keep a really high test coverage, since I cannot statically reason about my queries. I actually need to run them to see if they work at all.

Enter the stage: Postguard. Back to confidence and short feedback cycles.

Feedback

So this tool is still pretty damn young and should not be used for production code yet.

I would love to hear some feedback regarding the overall approach, though!

The concept might seem a bit esoteric, but the code feels quite natural.

Share anything that's on your mind :)

Happy hacking!