node / typescript workflows

Better node / typescript workflows

Today, it is possible to call arbitrary node code server side within a template literal.

I think this is cool but in practice it's not that ergonomic to work with, it's very stringly typed and you might need to escape your code (e.g. is there a template literal inside your template literal).

It also completely removes the ability to have typed languages because all that type information that would normally be analyzed by a compiler is "trapped" inside a string.

I suggest we build in support for hashed modules.

Hashed modules

Hashed modules simply copy a module's subtree in the same way we copy source code. But hashql generates a transformed replica of those modules (updating relative imports for example).

From an editors perspective it's just a dynamic import with an async default export. Both JS and TS will be able to find the original source file and identify the type information from that source file.

So if you have some js module, you can just dynamically import it and call it:

import('./my-lambda.js').then(
  ({ default:f }) => f({ a: 1, b: 2 })
)

Which is compiled to something like:

hashql.module(<hash-of-compiled-subtree>).then(
  ({ default:f }) => f({ a: 1, b: 2 })
)

The cool thing to note is, this is 100% typed. An IDE will chug along not knowing we've done anything at all to the source, and it will simply look at the originally referenced path and gather type information itself.

Typescript

The above will work with typescript, but hashql doesn't yet have an example of transpilation of source in the hashql handler. I think this is pretty easy to do as a build step, but it'd be good to have in /examples so people can figure it out. It'd also be good to have some ootb modules for rigging up common workflows (e.g. hashql-rollup-typescript or hashql/rollup/typescript).

Static Usage

This can definitely work for static imports too, with a few restrictions, all exported values are async.

So if you have a module:

export const a = 1

And you import it, a will be a Promise

import * as example from './example'

example.a.then(console.log) // logs 1

In practice that won't be too much of an issue, if you want code to run on the server it's likely async anyway. But I think it'd be valuable for the compile step to warn that a hashed module was imported with non async imports - to avoid confusion.

This problem is mitigated with dynamic imports because async is enforced, But I think we shouldn't exclude static imports, it just feels nice to do something like import * as api from './api' and then call api.createUser(user) from the client as if it was all in the same process.

Questions

How do we identify which imports should be hashed, and which shouldn't is an open question. We could have a comment, or we could have a config file with path globs. Because this doesn't use template literals it requires some new interface design work in that department.

Why?

This feature will give hashql editor support for free. There's no reason we can't take this same technique and use it with other language's module systems (e.g. python/rust/go), and those editors will all already know how to get the type information from those imports.

This relieves a lot of pressure from the library to do special custom things like generating tsd's or the like.

Start by reading the hashql handler and the existing material under /examples, then map how source copying, transformed relative imports, and TypeScript transpilation would fit together. The open questions around identifying hashed imports and supporting static versus dynamic imports need decisions before completion can be defined.