typescript checking frontend template files

[ducin]

The greatest feature of TypeScript, in terms of big enterprise apps, is type checking. When modifying/extending something low-level, I'll get all errors that arise beneath - just like I would in Java and .Net. But this relates to TS code.

My question is: is it possible to use TypeScript to check types used in frontend templating engines, such as Handlebars, Underscore or [your favourite templating engine]?
I've read that TypeScript 1.6 is gonna support react's JSX, but it's a big limitation to one specific engne only. I guess there is no built-in platform-supported solution, but maybe there is someone who made it work somehow?

Or, in other words, what would you do if you wanted to use TypeScript to check types of variables in handlebars/underscore templates?

[mhegazy]

This is an interesting topic, but I do not have any ideas here. the main problem i see, is that the html template and the JS code that populates its context are detached, and the linkage happens dynamically. JSX on the other hand does not have this issue, as the JSX elements are evaluated in the context of their declaration.

Would love to discuss ideas here on how to we can get the type checking in the html templates..

One option is to get the template compilers to generate .ts code instead of .js code and then the compiler can typecheck it, we could also use something akin of sourcemaps to make sure that errors are reported in your html template instead of in the generated .ts code.
this leaves us with the tooling, like suggestions while you are writing your html template, and i think the IDE's can use naming conventions to identify the context object you are using and then provide completions, goto definition, etc..

[ducin]

Considering the easiest example, underscore's _.template function:

var compiled = _.template("hello: <%= name %>");
compiled({name: 'moe'});
=> "hello: moe"

we should be able to decorate/extend the base function, so its contract remains the same (behaves the same way from the outside).

What we want here is to make typescript compiler throw errors, when non-existent variable is accessed in the template, right? In order to do so, one option mentioned is to generate typescript code from template files. This generated code would have to rely on strict types (other than any) to run typechecking.

I did a quick check, that typescript's typecheck doesn't rely on inheritance, but on field names:

class A {
    field1: string;
}

class B {
    field1: string;
}

class C {
    field2: string;
}

function hello(a: A) {
    return a.field1;
}

var a = new A();
var b = new B();
var c = new C();

console.log( hello(a) ); // passes, obvious
console.log( hello(b) ); // passes, although B and A are not related (!), no "extends", no "implements"
console.log( hello(c) ); // fails, because of missing property, obvious

This means that we could parse a template, analyse what variables/structures are used there, generate disposable interfaces with optional properties (one for each template) and use them to typecheck parameters of the compiled template. For example, having following underscore template:

var compiled = _.template("hello: <%= name %>, we've got <%= weather %> weather today!");

we could generate the disposable interface:

interface template_Gl0oerMwXZ {
    name?: string;
    weather?: string;
}

and use it as the type of the only input parameter of the function:

var compiled = function(templateVariables: template_Gl0oerMwXZ) {
    // do something
}

Then we decorate the template with real data. The correct invocation:

compiled({name: "moe", weather: "beautiful"});

passes, while the typo one (note weathar instead of weather):

compiled({name: "moe", weathar: "beautiful"});

fails with following error: Argument of type '{ name: string; weathar: string; }' is not assignable to parameter of type 'template_Gl0oerMwXZ'. Object literal may only specify known properties, and 'weathar' does not exist in type 'template_Gl0oerMwXZ'. The error tells exactly what is wrong, but it might also tell which file does the template come from.

I think that's what we need, in general. This idea has some unsolved problems, such as how to re-use external template compiling functions (underscore, handlebars, etc) beneath, but above proof of concept works as expected in the typescript console.

---

I didn't get the sourcemaps idea in that context (however I do know source maps in general). Does this solution require to extend typescript core (e.g. interpreting those source maps)?

---

Hope we can figure it out somehow, this would be a killer feature!

[ducin]

How to wrap the original _.template function with typechecking? I came up with following idea of a preprocessor... Each time typescript compiler encounters a template (be it a file or just inline template string), it scans it and produces following (or similar) typescript additional code:

interface template_Gl0oerMwXZ {
    name?: string;
    weather?: string;
}

function compiled_Gl0oerMwXZ(templateCode: string) {
    var compiled = _.template(templateCode);
    return function decorator_Gl0oerMwXZ(templateVariables: template_Gl0oerMwXZ) {
        return compiled(templateVariables);
    }
}

This code is linked to the original TS code. And for each occurence of _.template in original ts code, such as a backbone view (link code slightly modified):

  var SearchView = Backbone.View.extend({
    initialize: function(){
      this.render();
    },
    render: function(){
      // Compile the template using underscore
      var template = _.template( $("#search_template").html() );
      // Load the compiled HTML into the Backbone "el"
      this.$el.html( template( {abc: "def"}) );
    }

the preprocessor would replace:

var template = _.template( $("#search_template").html() );

with

var template = compiled_Gl0oerMwXZ( $("#search_template").html() );

The code would look like this:

  var SearchView = Backbone.View.extend({
    initialize: function(){
      this.render();
    },
    render: function(){
      // Compile the template using underscore
      var template = compiled_Gl0oerMwXZ( $("#search_template").html() );
// NOTE: template is decorator_Gl0oerMwXZ with template code enclosed in the closure
      // Load the compiled HTML into the Backbone "el"
      this.$el.html( template( {abc: "def"}) );
    }

Note that the closure function decorator_Gl0oerMwXZ would work out of the box.

So, for above example code, the preprocessor would generate:

interface template_Gl0oerMwXZ {
    name?: string;
    weather?: string;
}

function compiled_Gl0oerMwXZ(templateCode: string) {
    var compiled = _.template(templateCode);
    return function decorator_Gl0oerMwXZ(templateVariables: template_Gl0oerMwXZ) {
        return compiled(templateVariables);
    }
}

var SearchView = Backbone.View.extend({
    initialize: function () {
        this.render();
    },
    render: function () {
        // Compile the template using underscore
        var template = compiled_Gl0oerMwXZ( $("#search_template").html() );
        // Load the compiled HTML into the Backbone "el"
        this.$el.html(template( {abc: "def"} ));
    } });

and this would be now executed under standard typescript compiler, which would catch all errors.

Anyway, I'm trying to find an easier way...

[ducin]

For Handlebars:

var data = {
    users: [ { 
        person: {
            firstName: "Garry", 
            lastName: "Finch"
        },
        jobTitle: "Front End Technical Lead",
        twitter: "gazraa" 
    }, {
        person: {
            firstName: "Garry", 
            lastName: "Finch"
        }, 
        jobTitle: "Photographer",
        twitter: "photobasics"
    }, {
        person: {
            firstName: "Garry", 
            lastName: "Finch"
        }, 
        jobTitle: "LEGO Geek",
        twitter: "minifigures"
    } ]
}; 

Handlebars.registerHelper('fullName', function(person) {
  return person.firstName + " " + person.lastName;
});

$('body').append(template(data));

it could work exactly the same way (just with more advanced data structures, but it all seems parsable):

interface person_Gl0oerMwXZ {
    firstName?: string;
    lastName?: string;
}

interface usersElement_Gl0oerMwXZ {
    person?: person_Gl0oerMwXZ;
    jobTitle?: string;
    twitter?: string;
}

interface users_Gl0oerMwXZ {
    [i : number] : usersElement_Gl0oerMwXZ;
}

interface template_Gl0oerMwXZ {
    users?: users_Gl0oerMwXZ;
}

function compiled_Gl0oerMwXZ(templateCode: string) {
    var compiled = Handlebars.compile(templateCode);
    return function decorator_Gl0oerMwXZ(templateVariables: template_Gl0oerMwXZ) {
        return compiled(templateVariables);
    }
}

var source = $("#some-template").html(); 
var template = compiled_Gl0oerMwXZ(source); 
var data = {...};
$('body').append(template(data));

in above example this:

var template = Handlebars.compile(source);

has been replaced with:

var template = compiled_Gl0oerMwXZ(source);

Different templating engines

...just the preprocessor would need a different analyser for underscore and handlebars syntax. AngularJS templates seem more complicated, though...

Strict template properties

Handlebars' if syntax could determine whether auto-generated interfaces do contain ? for optional properties or not:

<div class="entry">
  {{#if author}}
    <h1>{{firstName}} {{lastName}}</h1>
  {{/if}}
</div>

in above case, this would generate optional author?: string; property. Without the if clause, author could be a required property. Or, for compatibility reasons, there could be a strict template mode or some other flags that would determine the ? presence in interfaces.

Above is handlebars's if syntax. Other syntax constructions could work the same way, just as each:

<ul class="people_list">
  {{#each people}}
    <li>{{this}}</li>
  {{/each}}
</ul>

that would determine, that a structure is a collection (just as users_Gl0oerMwXZ and usersElement_Gl0oerMwXZ above).

Template base type: String and/or Number

All above examples rely on strings. But numbers are valid atomic types of templating engines and should be supported by ts-based templates. And typescript compiler differentiates strings and numbers. Union types is a possible solution. Below code compiles with no errors:

interface person_Gl0oerMwXZ {
    firstName?: string|number;
    lastName?: string|number;
}

var p1: person_Gl0oerMwXZ = {
    firstName: "Tomasz",
    lastName: 123
} 

Since JavaScript doesn't check types, the original underscore/handlebars/whatever template code doesn't contain information about the type. So, probably, we'd need to state string|number; everywhere.

[mhegazy]

i think the inlined templates are different from template files. i would say the inlined templates resolution can be solved by #3136.

the standalone templates are different though. i do not think you want to infer types from them. you want to report errors there. e.g.

<div class="entry">
    <h1>{{lastname}}</h1>
</div>

i want to get an error that Class Entry does not have a property "lastname" cause i misspelled it, and it should have been "lastName" with a capital 'N'.

I think this is more useful than saying that this template expects a type with lastname and you passed it a type with lastName when the user instantiates it.

one other thing to consider, is you want tooling as well. in your VSCode/VS/Sublime/Eclipse/Webstorm/etc... you want to hit "goto def" on lastName and it takes you to your Entry class definition, or when you ask for "all references" to find this one as well, this way you can rename safely.

That is why i was saying the template compiler generates .ts code, with type annotations, that is "linked" to the template code some how, and then the TS compiler/Langage Service understands it as part of your program.

[ducin]

Regarding the Class Entry does not have a property "lastname" and the example code you pasted:

<div class="entry">
    <h1>{{lastname}}</h1>
</div>

I'm not sure if you want to enforce developers to use CSS class property that way? At least I can see no other place where Entry class is mentioned.

That is why i was saying the template compiler generates .ts code, with type annotations, that is "linked" to the template code some how, and then the TS compiler/Langage Service understands it as part of your program.

I was thinking about generating .ts code as well, basing on template code, that would specify the types. I'm afraid I know too little about TS compiler internals.

Let me know if I can help you further.

[mhegazy]

Sorry my bad. I did not mean the css class, that was just a copy/past from your example. I meant whatever "contex" object this template will be bound to at runtime, the one expected to have a property lastName.
One issue is to know what template file binds to at runtime, and I do not have much knowledge here...

[ducin]

Do you mean that, in order to suggest a solution, we need to divide all frontend templating engines into two groups:

1. compiled in compile-time
2. compiled in runtime
   ? If not, please, clarify, how can I help.

[mhegazy]

I do not think I have a solution :) I was just brain storming. I do agree that there is a need for better experience here. If you would like to champion this issue and drive a proposal I would be willing to help.

I think there is error reporting, either in the template as I mentioned or at the use side as you suggested; and the tooling support.

[styfle]

@ducin @mhegazy
I have been thinking about this problem since our team started getting bugs when refactoring and forgetting to change the handlebars templates. It's the one place in our code that is not type safe.

I implemented my own solution: typed-tmpl. Let me know what you think!