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 and MacOS, and will probably work on any Unix-like operating system. PRs to expand platform support are welcome! Note that Windows support is blocked by Cgo limitations, see Windows Support.

Pre-built binaries are available for Linux and MacOS on 64-bit x86 and ARM. If they are unavailable for your platform, the install script will try to build them automatically, which requires Go 1.20 or later.

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.

Windows Support

Cgo on Windows requires GCC and MinGW, which results in a native extension module that is ABI-incompatible with the standard Node releases built with MSVC.

MSYS2 ships a MinGW build of Node, and this package does work with that. But (as far as I know) that is not commonly used, and there does not seem to be a way to tell NPM that this package works on MinGW but not native win32. If you are using the MinGW build of Node and want to use this package, please file an issue to let me know!