go-text-template-napi

This library provides JavaScript bindings to Go's text/template package package via Node-API. Nearly the full API is supported, including custom template functions written in JavaScript.

For example, this JavaScript program:

import { Template } from 'go-text-template-napi';

const template = new Template('name')
  .funcs({ double: (l) => [...l, ...l] })
  .parse(`{{ range double .targets }}Hello, {{ . }}!\n{{ end }}`);
process.stdout.write(template.executeString({ targets: ['user', 'world'] }));

is equivalent to this Go program:

package main

import (
        "os"
        "text/template"
)

func double(list []any) []any {
        return append(list, list...)
}

func main() {
        tmpl := template.New("name").Funcs(template.FuncMap{"double": double})
        template.Must(tmpl.Parse("{{ range double .targets }}Hello, {{ . }}!\n{{ end }}"))
        err := tmpl.Execute(os.Stdout, map[string]any{"targets": []any{"user", "world"}})
        if err != nil {
                panic(err)
        }
}

Both output:

Hello, user!
Hello, world!
Hello, user!
Hello, world!

WARNING: Do not use this library with untrusted templates, and use extreme caution when passing untrusted data to trusted templates. See the Warnings section for more details.

Experimental Sprig Support

Sprig template functions can be enabled by calling the addSprigFuncs method on Template. This API is subject to change.

Requirements

The native component requires Node-API version 8, which is available on all supported release lines of Node. It's tested on Linux, MacOS, and Windows, and will probably work on any other platform supported by Node. PRs to expand platform support are welcome!

Pre-built binaries are available for Linux and MacOS on 64-bit x86 and ARM, and for Windows on 64-bit x86. If they are unavailable for your platform, the install script will try to build them automatically, which requires Go 1.21 or later. On Windows, due to Cgo requirements, you will also need GCC/MinGW.

Warnings

Importing this package will spin up a Go runtime within your Node process. Should this library have a bug that results in a Go panic, it will take the entire process with it.

Additionally, be aware that Go's memory usage is not subject to Node's heap size limits. Be sure that adequate additional memory is available if your workload causes significant Go memory usage.

This library currently buffers the full template output with no size limit, so an untrusted template can trivially DoS your application by generating an output larger than your available memory.

API Limitations

A few less-useful parts of the API are unimplemented:

• The parse subpackage and related functions (they're documented as internal interfaces)
• All functions operating on a fs.FS virtual fileystem
• The *Escape helper functions that write to a io.Writer

Additionally, the Execute and ExecuteTemplate methods return strings instead of taking a Writer parameter. This is faster than a streaming interface given the FFI overhead, but it also makes it impossible to limit the memory usage of untrusted templates (per the Warnings section). Support for the streaming interface is planned for future releases.