Feature: Provide Babel Macro to avoid extra build step

[zenflow]

If we provide a "Babel Macro" (plugin for babel-plugin-macros), then users can avoid having an extra build step using the ts-interface-builder CLI.

Users could write something like this in their source:

import { getCheckers } from 'ts-interface-builder/macro'
import { ISomeConfig } from './types'

const checkers: ICheckerSuite = getCheckers('./types')

export function validateSomeConfig(config: any): ISomeConfig {
  checkers.ISomeConfig.check(config)
  return config as ISomeConfig
}

Compiled to JavaScript

import { getCheckers } from 'ts-interface-builder/macro'

const checkers = getCheckers('./types')

export function validateSomeConfig(config) {
  checkers.ISomeConfig.check(config)
  return config
}

After the babel-plugin-macros transform it would look like this:

import * as t from 'ts-interface-checker'

const checkers = t.createCheckers({
  ISomeConfig: t.iface([], {
    // ... ISomeConfig described here ...
  })
})

export function validateSomeConfig(config) {
  checkers.ISomeConfig.check(config)
  return config
}

p.s. babel-plugin-macros is a really popular plugin and comes preloaded in some frameworks' Babel configs, like Create React App and tsdx.

What do you think @dsagal ?

I'm about to try implementing this. If I get it working as I envision, will you review a PR to add the feature here?

P.S. Thank you for the incredible packages! ❤️ They are saving me a lot of repetition in my code for runtime config validation! (Repetition that would have also been verbose and ugly, using a 2nd DSL to describe types 🤮, like with AJV or Yup or Superstruct)

[dsagal]

Sounds exciting :) I am not using Babel and so not familiar with its macros, but sure, would be glad to review a PR to add support on ts-interface-builder's side.

[zenflow]

So, my first-round implementation of this (at the beginning of PR #24) didn't cover these two things (listed in the PR message):

1. instead of just makeCheckers(...): ICheckerSuite, also offer edit buildTypeSuite(...): ITypeSuite, to give the option of more control to users, and so they can possibly build & compose/merge multiple type suites and call t.createCheckers directly with the result.
2. should never inline the same checker suite expression more than once in same file

To fix this, these changes to the original proposal (above), the following should be the output for the input of the original example:

import * as t from 'ts-interface-checker'

function once(fn) {
  var result;
  return function () {
    return result || (result = fn());
  };
}

var typeSuite0 = once(function () {
  return {
    ISomeConfig: t.iface([], {
      // ... ISomeConfig described here ...
    })
  }
})

var checkerSuite0 = once(function () {
  return t.createCheckers(typeSuite0())
})

const checkers = checkerSuite0()

export function validateSomeConfig(config) {
  checkers.ISomeConfig.check(config)
  return config
}

This format ensures that

1. the same type suite expression is not inlined more than once in the same file (no matter the combination of calls to getCheckers & getTypeSuite)
2. the same checker suite is not created via getCheckers more than once in the same file
3. checker suite creation happens on-demand, and not necessarily during module loading. The user can call getCheckers() in the module scope to create the checker suite during module loading, or they can call getCheckers()` just when it's needed, and the checker suite will be created lazily/on-demand.

@dsagal Is point # 3 necessary? Is the computation of creating the checker suite expensive? If not really, then we can ditch that point.

[zenflow]

My main concern for closing this issue is the issue of whether this functionality should be part of this package, or a fresh new package:

My only reservation is that as part of the ts-interface-builder package, the macro's tests are guaranteed to be passing whenever you make changes to ts-interface-builder. This is only a concern because the macro's implementation relies on on the Compiler to output a very specific (but very simple) format for format: 'js:cjs'. The output should be two statements: ... t = require("ts-interface-checker"); and module.exports = { ... };.
#24 (comment)

I think we can solve this with a simple check on the CJS output in the unit tests. It can check the text of the first two lines (which should be "import * as t from 'ts-interface-checker'" and a blank line), and the rest of the text (which should match /^module\.exports = \{.*\};$/m)

@dsagal Does that sound OK?

[dsagal]

3. checker suite creation happens on-demand, and not necessarily during module loading. The user can call `getCheckers() in the module scope to create the checker suite during module loading, or they can call `getCheckers()` just when it's needed, and the checker suite will be created lazily/on-demand.

@dsagal Is point # 3 necessary? Is the computation of creating the checker suite expensive? If not really, then we can ditch that point.

(Sorry about the delay!)
Probably not necessary. I just timed a typesuite of about 30 lines -- it takes about 7us to create the type suite, and 18us to create checkers from it. Something much larger could get into milliseconds. Your pattern doesn't hurt though, it may be a good idea in some cases. But not necessary. One benefit of NOT deferring instantiation is that if anything is wrong (e.g. during code generation), the mistake would be known at load time, rather than some time later at run-time.

I think we can solve this with a simple check on the CJS output in the unit tests. It can check the text of the first two lines (which should be "import * as t from 'ts-interface-checker'" and a blank line), and the rest of the text (which should match /^module\.exports = \{.*\};$/m)

That sounds OK, as does adding an option for "js:expression" output. Up to you!

[zenflow]

Ugh.. GitHub says this issue was closed with 86cb1d6 but that's wrong and that commit was not merged. This is the right commit is e87d585. The PR was #24.