@foxfriends/embedded-typescript

Embedded TypeScript

Type safe TypeScript templates

What is this? 🧐

A type safe templating system for TypeScript. Templates are compiled to TypeScript files that you then import for type safe string generation.

This templating system draws inspiration from ERB, EJS, handlebars and mustache. This project embraces the "just JavaScript" spirit of ejs and adds some of the helpful white space semantics of mustache.

Checkout the examples or play with embedded-typescript in your browser.

Installation & Usage 📦

1. Add this package to your project:

   npm install @foxfriends/embedded-typescript or yarn add @foxfriends/embedded-typescript

Motivation

Hello undefined!

When using a typed language, I want my templates to be type checked. For most cases, template literals work well, but template literals quickly become difficult to maintain as the template complexity grows. I can switch to EJS, handlebars, mustache, etc, but then I lose the type safety I had with template literals. Sometimes I want the expressiveness of a templating language without losing type safety. For those cases, I wrote embedded-typescript.

Syntax

Syntax	Name	Description
--- CODE ---	Header	Defines code that should live outside of the generated render function. Use this to define Props and any imports, exports or constants.
<%= EXPRESSION %>	Expression	Inserts the value of an expression. This value is escaped according to the detected file type mode.
<%~ EXPRESSION %>	RawExpression	Inserts the value of an expression.
<%| EXPRESSION %>	PreserveIndent	Inserts the escaped value of an expression. If the expression generates multiple lines, the indentation level is preserved across all resulting lines.
<%~| EXPRESSION %>	RawPreserveIndent	Inserts the value of an expression. If the expression generates multiple lines, the indentation level is preserved across all resulting lines.
<% CODE %>	Statement	Executes code, but does not insert a value.
<>	Glue	Glues this line and the next one together by deleting exactly 1 following \n character.
TEXT	Text	Text literals are inserted as is. All white space is preserved.

Examples 🚀

Minimal

1. Write a template file: my-template.ets:

---
interface Props {
  users: {
    name: string;
  }[]
}
---
<% for (const user of props.users) { %><>
Name: <%= user.name %>
<% } %><>

2. Run the compiler: npx ets. This will compile any files with the .ets extension. my-template.ets.ts will be generated.

3. Import the generated .ets.ts file wherever you'd like to render your template:

import render from "./my-template.ets";

/* will output:
Name: Alice
Name: Bob
*/

console.log(render({ users: [{ name: "Alice" }, { name: "Bob" }] }));

Note that the arguments to your template function are type checked. You define the arguments to your template function by defining a type or interface named Props.

Partials

Embedded TypeScript preserves the indentation wherever an expression tag (<%= EXPRESSION %>) is used. This means there isn't any special syntax for partials, and ets templates nest as you would expect.

1. Write a "partial" user-partial.ets:

---
interface Props {
  name: string;
  email: string;
  phone: string;
}
---
Name: <%= props.user.name %>
Email: <%= props.user.email %>
Phone: <%= props.user.phone %>

Note there is nothing special about user-partial.ets, it's just an ets template. We're using the -partial suffix purely for illustration.

2. Import your "partial" into another ets template my-template-2.ets:

---
import renderUser, { Props as User } from './user-partial.ets';

interface Props {
  users: User[];
}

const example =
`1
2
3
4`;
---
<% if (props.users.length > 0) { %><>
Here is a list of users:

  <% for (const user of props.users) { %><>
  <%| renderUser(user) %>
  <% } %><>

<% } %><>
The indentation level may be preserved for the rendered 'partial'.

There isn't anything special about the 'partial'. Here we used another `.ets` template, but any
expression yeilding a multiline string would be treated the same.

  <%| example %>

The end!

3. Run the compiler: npx ets.

4. Import the generated my-template-2.ets.ts file wherever you'd like to render your template:

import render from "./my-template-2.ets";

/* will output:
Here is a list of users:

  Name: Tate
  Email: [e-mail]
  Phone: [phone]

  Name: Emily
  Email: [e-mail]
  Phone: [phone]

The indentation level is preserved for the rendered 'partial'.

There isn't anything special about the 'partial'. Here we used another `ets` template, but any
expression yielding a multi-line string would be treated the same.

  1
  2
  3
  4

The end!
*/

console.log(
  render({
    users: [
      { name: "Tate", phone: "888-888-8888", email: "[e-mail]" },
      { name: "Emily", phone: "777-777-7777", email: "[e-mail]" },
    ],
  })
);

Note that indentation was preserved for all lines rendered by user-partial.ets and all lines of the example variable due to the use of the <%| interpolation. Any expression yielding a multi-line string rendered inside an expresssion block (<%| EXPRESSION %>) will apply the indentation across each line.

More Examples

For more examples, take a look at the e2e directory. The *.ets.ts files are generated by the compiler from the *.ets template files. The corresponding *${NAME}.test.ts shows example usage and output.

Async partials

In order to use async/await in a partial, the file extension must be .async.ets. The resulting template function that is generated will be an async function respectively, and will need to be await-ed when used.

HTML mode

When the file extension is .html.ets (or .html.async.ets or .async.html.ets), the template is considered in HTML mode. The only change is to the behaviour of <%= and <%| interpolations: special characters in such interpolated strings will be HTML-escaped.

If you need to output those characters un-changed (e.g. because you're embedding a partial into another partial), use <%~ or <%~|.

Understanding Error Messages

The compiler will output errors when it encounters invalid syntax:

error: Unexpected closing tag '%>'
   --> ./template-1.ets:4:41
    |
4   | <% users.forEach(function(user) { %>%>
    |                                     ^
    |                                     |
...

The first line is a description of the error that was encountered.

The second line is location of the error, in path:line:column notation.

The next 5 lines provide visual context for the error.

Highlights

🎁 Zero run time dependencies

Configuration 🛠

Embedded TypeScript aims to be zero config, but can be configured by creating an ets.config.mjs (or .js or .cjs) file in your project root.

Name	Description	Type
source	The root directory. `.ets` files will be searched under this directory. Embedded TypeScript will recursively search all subdirectories for `.ets` files. Defaults to the project root. Example: Search for .ets files under a directory named src // ets.config.mjs ```js /** @type {import('ets').Config} */ export default { source: "src", }; ```	string (filepath)

Contributing 👫

PR's and issues welcomed! For more guidance check out CONTRIBUTING.md

Licensing 📃

See the project's MIT License.