refactor(ssr): add back references to esTemplate and infer types

[wjhsf]

Before:

const bYieldEscapedString = esTemplateWithYield<
    EsStatement[],
    [
        EsIdentifier,
        EsExpression,
        EsIdentifier,
        EsLiteral,
        EsIdentifier,
        EsIdentifier,
        EsIdentifier,
        EsIdentifier,
        EsIdentifier,
    ]
>`
    const ${is.identifier} = ${is.expression};
    if (typeof ${is.identifier} === 'string') {
        yield (${is.literal} && ${is.identifier} === '') ? '\\u200D' : htmlEscape(${is.identifier});
    } else if (typeof ${is.identifier} === 'number') {
        yield ${is.identifier}.toString();
    } else {
        yield htmlEscape((${is.identifier} ?? '').toString());
    }
`;

const ast = bYieldEscapedString(
    tempVariable,
    valueToYield,
    tempVariable,
    isIsolatedTextNode,
    tempVariable,
    tempVariable,
    tempVariable,
    tempVariable,
    tempVariable
);

After:

const bYieldEscapedString = esTemplateWithYield`
    const ${is.identifier} = ${is.expression};
    if (typeof ${0} === 'string') {
        yield (${is.literal} && ${0} === '') ? '\\u200D' : htmlEscape(${0});
    } else if (typeof ${0} === 'number') {
        yield ${0}.toString();
    } else {
        yield ${0} ? htmlEscape(${0}.toString()) : '\\u200D';
    }
`<EsStatement[]>;

const ast = bYieldEscapedString(
    tempVariable,
    valueToYield,
    isIsolatedTextNode
);

Details

esTemplate is a template tag that can be applied to a string containing JavaScript code, and it returns a function that generates the estree AST for that code. "Holes" can be introduced into the AST by providing node validators as expressions in the template string (e.g. ${is.identifier}, above). When a hole is introduced, it is filled by a parameter passed to the generated template function (e.g. providing tempVariable to bYieldEscapedString, above). The generated function pairs parameters to validators, to ensure that a valid AST is generated. The type signature of the generated function matches the types validated by each validator. The return type is a generic parameter that must be provided explicitly, because TypeScript has no way of knowing what it should be.

With the current implementation, you must provide a parameter once for every hole, even if the value is used more than once (e.g .tempVariable, above). This PR introduces the concept of back references; a hole can now be filled by either a validator or a number. If a validator is provided, that validator corresponds to a parameter in the generated function. If a number is provided, the parameter from the specified index is re-used. In the example above, ${0} is used multiple times to indicate that value from tempVariable should be inserted at multiple points. This reduces the number of parameters required by the function from 9 to 3.

Additionally, in the current implementation, the requirement that the return type is provided as an explicit generic parameter means that the generated function arguments must also be explicitly stated. (Type inference for generic parameters is all or nothing -- it can't infer just one.) However, because esTemplate is a function that returns a function, I've split the two generic parameters and moved the generic for the return type to the generated function. As a result, the generated function arguments can now be inferred! An interesting quirk of doing this is that the generic comes at the end of the statement, rather than the start (e.g .esTemplate`() => {}`<ArrowFunctionExpression>). The astute may note that this is technically not correct, because the return type is determined by the parameters of esTemplate, rather than the parameters of the generated function. I think that it's a fine trade off, though, given our controlled usage.

Does this pull request introduce a breaking change?

• 😮‍💨 No, it does not introduce a breaking change.

Does this pull request introduce an observable change?

• 🤞 No, it does not introduce an observable change.

GUS work item

[wjhsf]

This type does a lot of heavy lifting! To perform array operations (map/filter/etc.) in TypeScript, you have to resort to recursion. The general pattern looks like this:

// T -> Whatever
type ChangeValue<T> = Whatever

// T[] -> Whatever[]
type ChangeArray<Arr extends unknown[]> = Arr extends [infer Head, ...infer Rest]
  // If the array has one or more items, change the first, then recursively change the rest
  ? [ChangeValue<Head>, ...ChangeArray<Rest>]
  // The array is already empty -- don't need to do anything
  : []

// Filter values not assignable to `BaseType`
type FilterArray<Arr extends unknown[], BaseType> = Arr extends [infer Head, ...infer Rest]
  ? Head extends Basetype
    ? [Head, ...FilterArray<Rest>] // keep the value
    : FilterArray<Rest> // ditch the value
  : [] // array is already empty

Within that pattern, we use the infer keyword to extract the validated types from the validators. For example:

type PromiseValue<P extends Promise<any>> = P extends Promise<infer T> ? T : never
type PromisedAbc = Promise<'abc'>
type Abc = PromiseValue<PromisedAbc> // 'abc'

Sprinkle a few edge cases into the mix (as described in code comments), and you get this delightful monstrosity!

[nolanlawson]

I'm not going to pretend to understand the TypeScript gymnastics, but I like the backreferences! Amazing work.

[wjhsf]

@nolanlawson cleaned this up a bit!