docs: add Go templates alternative proposal

[ilya-lesikov]

No description provided.

[DmitryBochkarev]

I love the direction of this proposal!

I have several things to discuss if you don't mind, regarding the scope of implementation and developer productivity gained.

Support of JavaScript along with TypeScript

Modern JS with JSDoc gives comparable development experience to TypeScript. Most modern editors support it out of the box or with minimal setup steps. LLMs can catch them immediately and can do a pretty good job not messing up with types.

JavaScript without types allows making prototypes fast and moving quickly when needed. And later, gradually improve the codebase with proper JSDoc or migrate to TypeScript.

TypeScript compiler can check JavaScript with JSDoc (htmx example), which covers compile-time checks.

Gains

Compile-time checks overall. This is huge, no doubt.

Also, implementing support for this feature unlocks the ability to perform rich assertions on values during render:

• assert that conflicting features are not specified in passed values
• schema validation of custom resource manifests
• validate that all required security policies are applied

Personally, this is the most important part of this feature. It helps ensure that the result is rendered correctly, is valid, and that manifests are sound.

Hard parts of implementing TypeScript compilation

Because TypeScript is translated to JavaScript, there are risks of getting a bad development experience on errors. I believe support for source maps should be implemented as early as possible, so early adopters of this feature will not struggle with debugging if something fails during the render step.

Directory name

I think the directory should be named something complementary to the current templates and not specify the source language of charts:

• code - language neutral, which means that the project can be in TS or JS and the entry point is specified in package.json
• gen - more on the opposite side of templates, as in code generation rather than rendering

Helm helpers

Sadly, because of poor functionality of current charts, there are cases where Helm helpers are used in values. To move charts to the proposed feature will require rewrites of these values, which can be difficult.

Off the top of my head, there are tpl and include.

tpl, for example, can be used to generate some values based on other values: tpl '{{.Chart.Name}}-backend' ..

This is a bad practice which ideally should not be present in the first place, but it is applied, sadly, in practice. However, the tpl helper can be replaced using some JS library like mustache.js, which is eval-free and close to tpl.

Hermeticity and determinism

I believe it can be achieved by implementing a proper sandbox and API exposed to the JS runtime. There are a limited number of APIs available that introduce non-determinism. However, current Helm helpers contain non-deterministic methods (randAlphaNum, randAlpha, randNumeric, and randAscii). Maybe this is not such a big problem after all, and users can control this by redefining the standard API provided by the runtime.

JavaScript standard library that should be exposed at runtime

I believe that we should expose some of JavaScript's standard library to the user or exclude with a warning if used:

• console - for debugging purposes and generating custom messages during rendering
• Math - some JS libraries expect random to generate IDs
• Date - complementary to Helm helpers and same case as with Math for generating time-based UIDs
• crypto
• RegExp
• eval, Function should be considered unsafe and not available at runtime, imho

Node.js native extensions

Some JavaScript packages require a proper Node.js-compatible environment and are implemented as native extensions or include WASM modules. There should be a clear statement that only plain TS and JS dependencies are supported. Maybe there should be a warning about that.

Node.js/Browsers vs QJS, and general promise of supported features

Node.js/Browsers have stable and rich APIs which will continue to expand (my approximation :=)). On the other side, Nelm can't support experimental JS features or features outside of some base version. I propose to describe what ES version is supported and future expectations from Nelm. Maybe provide users with clear instructions on how they can use new features of JS and what risks this introduces (mismatch of locations in backtraces on errors).

Final note

I really whant this feature to be implemented, because i suffer refactoring charts on hands. So maybe scope of this feature can be reduced by implementing a only javascript support without build step and leave it up to user.

[DmitryBochkarev]

Should we support main section for package.json to override entry point?

• https://docs.npmjs.com/cli/v11/configuring-npm/package-json#main

[ilya-lesikov]

I think we should try esbuild (ts/ES5.1+ > ES5.1) to goja, without WASM. Both esbuild and goja are embedded. Node.js compatibility layer for goja might help too.

Support of JavaScript along with TypeScript

I think we should go for TypeScript, from what I can google most recommend TS over JSDoc. And as I understand you can use both TS and JSDoc. Also you can still use JS and JSDoc if you want.

Hard parts of implementing TypeScript compilation

Goja claims to have source maps support. I guess we can build source maps and save them into the chart during chart publishing, as we do with ts/vendor/libs.js.

Directory name

I'd still go with ts directory name. I want to leave space for other languages to be added, although unlikely. And I'd prefer ts over js: I think we should push for TS over JS, this seems the consensus. E. g. cdk8s and pulumi everywhere talk about TS, not JS.

Helm helpers

I'd avoid tpl and include for now I guess. We can always add it later, but this is a complex thing, and its ugly. We can ship without it surely.

JavaScript standard library that should be exposed at runtime

I think we should expose JS standard library. Not sure whether we should try to ship something like Helm library functions. Maybe it's better to make users figure it out and use the libraries they want.

Node.js native extensions

Will mention this in the docs. Otherwise it's probably fine to just make it fail with whatever error. If errors won't be clear then we'll think on it.

So maybe scope of this feature can be reduced by implementing a only javascript support without build step and leave it up to user.

I guess we can just do JS first. But I'm not sure there is even much to do to add TS support. We will already have transpiling ES5.1+ to ES5.1 with embedded esbuild (which is also be used in nelm chart dependency upload/pack), so we can go the same way for TS to ES5.1.