timonel 2.13.0-beta.1 → 2.14.0-beta.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [2.14.0-beta.1](https://github.com/KenkoGeek/timonel/compare/v2.13.0...v2.14.0-beta.1) (2025-11-28)
+
+### Features
+
+- **cli:** add Helm helpers (helmIf, helmWith) to templates and new release ([#201](https://github.com/KenkoGeek/timonel/issues/201)) ([b5ecb0f](https://github.com/KenkoGeek/timonel/commit/b5ecb0f29b207f7ff225b971c6e698bbc2d26073))
+
+# [2.13.0](https://github.com/KenkoGeek/timonel/compare/v2.12.2...v2.13.0) (2025-11-24)
+
+### Features
+
+- **core:** exporting createHelmExpression() from helmYamlSerializer ([#196](https://github.com/KenkoGeek/timonel/issues/196)) ([e9ee2d0](https://github.com/KenkoGeek/timonel/commit/e9ee2d08b6ad305e0652c53e7756240793987861))
+
 # [2.13.0-beta.1](https://github.com/KenkoGeek/timonel/compare/v2.12.2...v2.13.0-beta.1) (2025-11-24)
 
 ### Features

package/README.md

@@ -18,6 +18,8 @@ directory.
 ## ✨ Key Features
 
 - **🔒 Type-safe API** with strict TypeScript and cdk8s constructs
+- **🎯 Type-Safe Helm Helpers** with 9 composable template helpers (`helmIf`, `helmRange`,
+  `helmWith`, `helmInclude`, etc.)
 - **🔧 Flexible resource creation** with built-in methods and `addManifest()` for custom resources
 - **🌍 Multi-environment support** with automatic values files generation
 - **☂️ Umbrella Charts** for managing multiple subcharts as a single unit
@@ -72,33 +74,58 @@ tl umbrella synth
 ### Simple Web Application
 
 ```typescript
-import { Chart } from 'cdk8s';
-import { Deployment, Service } from 'cdk8s-plus-33';
-
-export class WebAppChart extends Chart {
-  constructor(scope: Chart, id: string) {
-    super(scope, id);
-
-    // Create deployment
-    new Deployment(this, 'web-deployment', {
-      containers: [
-        {
-          image: 'nginx:latest',
-          port: 80,
-          env: {
-            NGINX_PORT: '80',
-          },
+import { Rutter, helmInclude, createHelmExpression as helm } from 'timonel';
+
+const chart = new Rutter({
+  meta: {
+    name: 'web-app',
+    version: '1.0.0',
+    description: 'Simple web application',
+  },
+  defaultValues: {
+    replicas: 3,
+    image: {
+      repository: 'nginx',
+      tag: 'latest',
+    },
+  },
+});
+
+// Add Deployment with type-safe helpers
+chart.addManifest(
+  {
+    apiVersion: 'apps/v1',
+    kind: 'Deployment',
+    metadata: {
+      name: helmInclude('chart.fullname', '.'),
+      labels: helmInclude('chart.labels', '.', { pipe: 'nindent 4' }),
+    },
+    spec: {
+      replicas: helm('{{ .Values.replicas }}'),
+      selector: {
+        matchLabels: helmInclude('chart.selectorLabels', '.', { pipe: 'nindent 6' }),
+      },
+      template: {
+        metadata: {
+          labels: helmInclude('chart.selectorLabels', '.', { pipe: 'nindent 8' }),
         },
-      ],
-    });
-
-    // Create service
-    new Service(this, 'web-service', {
-      selector: { app: 'web' },
-      ports: [{ port: 80, targetPort: 80 }],
-    });
-  }
-}
+        spec: {
+          containers: [
+            {
+              name: 'web',
+              image: helm('{{ .Values.image.repository }}:{{ .Values.image.tag }}'),
+              ports: [{ containerPort: 80, name: 'http' }],
+            },
+          ],
+        },
+      },
+    },
+  },
+  'deployment',
+);
+
+// Generate the chart
+chart.write('./dist');
 ```
 
 ### Umbrella Chart with Multiple Services
@@ -126,6 +153,23 @@ const umbrellaConfig = {
 export const umbrella = new UmbrellaChartTemplate(umbrellaConfig);
 ```
 
+### Type-Safe Helm Helpers
+
+Timonel provides 9 composable, type-safe helpers for Helm template generation: `helmIf`,
+`helmRange`, `helmWith`, `helmInclude`, `helmDefine`, `helmVar`, `helmBlock`, `helmComment`, and
+`helmFragment`.
+
+**Benefits:**
+
+- ✅ 100% Type-Safe - catch errors at compile time
+- ✅ No Raw Strings - eliminate manual template interpolation
+- ✅ Composable - nest and combine helpers freely
+- ✅ Full IDE Support - autocomplete and type hints
+
+**Learn more:** See the
+[Type-Safe Helm Helpers Guide](https://github.com/KenkoGeek/timonel/wiki/Helm-Helpers-System) for
+complete documentation, examples, and best practices.
+
 ## 📚 Documentation
 
 - **[API Reference](https://github.com/KenkoGeek/timonel/wiki/API-Reference)** - Complete API

package/dist/index.d.ts

@@ -11,4 +11,6 @@ export type { KarpenterDisruption, KarpenterDisruptionBudget, KarpenterEC2NodeCl
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { AWS_HELPERS, createHelper, FILE_ACCESS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, getHelpersByCategory, KUBERNETES_HELPERS, SPRIG_HELPERS, STANDARD_HELPERS, TEMPLATE_FUNCTION_HELPERS, type HelperDefinition, } from './lib/utils/helmHelpers.js';
 export { createLogger, logger, LogLevel, TimonelLogger, type LogContext, type LoggerConfig, } from './lib/utils/logger.js';
-export { createHelmExpression, isHelmExpression, type HelmExpression, } from './lib/utils/helmYamlSerializer.js';
+export { UmbrellaRutter } from './lib/umbrellaRutter.js';
+export { helmIf, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, type HelmConstruct, type HelmExpression, type HelmContent, type HelmWhitespaceOptions, } from './lib/utils/helmControlStructures.js';
+export { dumpHelmAwareYaml, validateHelmYaml, type HelmValidationError, type HelmValidationResult, } from './lib/utils/helmYamlSerializer.js';

package/dist/index.js

@@ -8,4 +8,6 @@ export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { AWS_HELPERS, createHelper, FILE_ACCESS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, getHelpersByCategory, KUBERNETES_HELPERS, SPRIG_HELPERS, STANDARD_HELPERS, TEMPLATE_FUNCTION_HELPERS, } from './lib/utils/helmHelpers.js';
 export { createLogger, logger, LogLevel, TimonelLogger, } from './lib/utils/logger.js';
-export { createHelmExpression, isHelmExpression, } from './lib/utils/helmYamlSerializer.js';
+export { UmbrellaRutter } from './lib/umbrellaRutter.js';
+export { helmIf, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, } from './lib/utils/helmControlStructures.js';
+export { dumpHelmAwareYaml, validateHelmYaml, } from './lib/utils/helmYamlSerializer.js';

package/dist/lib/rutter.d.ts

@@ -93,18 +93,6 @@ export declare class Rutter {
         target: string;
     }>;
     private toSynthArray;
-    private processHelmTemplates;
-    private fixCharacterMappingIssues;
-    private processCharacterMapping;
-    private applyHelmTemplateReplacements;
-    private fixIncludeStatements;
-    private fixFunctionCalls;
-    private fixChartReferences;
-    private removeHelmExpressionQuotes;
-    private fixConditionalBlocks;
-    private fixPipeExpressions;
-    private fixNestedQuotes;
-    private cleanupArtifacts;
     write(outDir: string): void;
 }
 export interface ChartMetadata {

package/dist/lib/rutter.js

@@ -1,10 +1,11 @@
 import { ApiObject, App, Chart, Testing } from 'cdk8s';
-import * as jsYaml from 'js-yaml';
+import { parse } from 'yaml';
 import { include } from './helm.js';
 import { HelmChartWriter } from './helmChartWriter.js';
 import { AWSResources } from './resources/cloud/aws/awsResources.js';
 import { createLogger } from './utils/logger.js';
 import { KarpenterResources } from './resources/cloud/aws/karpenterResources.js';
+import { isHelmExpression, isHelmConstruct } from './utils/helmControlStructures.js';
 import { dumpHelmAwareYaml } from './utils/helmYamlSerializer.js';
 import { generateHelpersTemplate } from './utils/helmHelpers.js';
 export class Rutter {
@@ -63,7 +64,7 @@ export class Rutter {
         let manifestObject;
         if (typeof yamlOrObject === 'string') {
             try {
-                manifestObject = jsYaml.load(yamlOrObject);
+                manifestObject = parse(yamlOrObject);
             }
             catch (error) {
                 throw new Error(`Invalid YAML provided to addManifest(): ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -76,12 +77,13 @@ export class Rutter {
             throw new Error('addManifest() requires either a YAML string or an object');
         }
         this.validateManifestStructure(manifestObject);
-        return new ApiObject(this.chart, id, {
-            apiVersion: manifestObject['apiVersion'],
-            kind: manifestObject['kind'],
-            metadata: manifestObject['metadata'],
-            spec: manifestObject['spec'],
-        });
+        const apiObjectProps = {
+            apiVersion: manifestObject.apiVersion,
+            kind: manifestObject.kind,
+            metadata: manifestObject.metadata,
+            ...manifestObject,
+        };
+        return new ApiObject(this.chart, id, apiObjectProps);
     }
     addTemplateManifest(yamlTemplate, id) {
         const templateAsset = {
@@ -169,13 +171,10 @@ ${yamlContent.trim()}
             });
             throw new Error('Manifest metadata must have a name');
         }
-        if (typeof metadata.name !== 'string') {
-            this.logger.error('Validation failed: metadata.name must be a string', {
-                operation: 'manifest_validation',
-                issue: 'invalid_metadata_name_type',
-                actual_type: typeof metadata.name,
-            });
-            throw new Error('Manifest metadata.name must be a string');
+        const name = manifest['metadata']?.['name'];
+        if (typeof name !== 'string' && !isHelmExpression(name) && !isHelmConstruct(name)) {
+            const actualType = Array.isArray(name) ? 'array' : name === null ? 'null' : typeof name;
+            throw new Error(`Manifest metadata.name must be a string, HelmExpression, or HelmConstruct. Got ${actualType}`);
         }
     }
     getMeta() {
@@ -242,7 +241,7 @@ ${yamlContent.trim()}
         const synthAssets = [];
         if (this.props.singleManifestFile) {
             const combinedYaml = enriched
-                .map((obj) => this.processHelmTemplates(dumpHelmAwareYaml(obj).trim()))
+                .map((obj) => dumpHelmAwareYaml(obj).trim())
                 .filter(Boolean)
                 .join('\n---\n');
             const manifestId = this.props.manifestPrefix ?? 'manifests';
@@ -252,7 +251,7 @@ ${yamlContent.trim()}
             enriched.forEach((obj, index) => {
                 const apiObjectId = apiObjectIds[index];
                 const manifestId = apiObjectId || `manifest-${index + 1}`;
-                const yaml = this.processHelmTemplates(dumpHelmAwareYaml(obj).trim());
+                const yaml = dumpHelmAwareYaml(obj).trim();
                 if (yaml) {
                     synthAssets.push({ id: manifestId, yaml });
                 }
@@ -270,173 +269,6 @@ ${yamlContent.trim()}
         timer();
         return synthAssets;
     }
-    processHelmTemplates(yaml) {
-        let processed = this.fixCharacterMappingIssues(yaml);
-        processed = this.applyHelmTemplateReplacements(processed);
-        return processed;
-    }
-    fixCharacterMappingIssues(yaml) {
-        const lines = yaml.split('\n');
-        const fixedLines = [];
-        let i = 0;
-        while (i < lines.length) {
-            const line = lines[i];
-            if (!line) {
-                i++;
-                continue;
-            }
-            const charKeyMatch = line.match(/^(\s*)"(\d+)":\s*(.+)$/);
-            if (charKeyMatch && charKeyMatch[2] && parseInt(charKeyMatch[2]) === 0) {
-                const indent = charKeyMatch[1] || '';
-                const result = this.processCharacterMapping(lines, i, indent);
-                if (result.reconstructed) {
-                    fixedLines.push(result.reconstructed);
-                    i = result.nextIndex;
-                    continue;
-                }
-            }
-            if (line) {
-                fixedLines.push(line);
-            }
-            i++;
-        }
-        return fixedLines.join('\n');
-    }
-    processCharacterMapping(lines, startIndex, indent) {
-        const charMappings = [];
-        let j = startIndex;
-        while (j < lines.length) {
-            const currentLine = lines[j];
-            if (!currentLine) {
-                break;
-            }
-            const currentMatch = currentLine.match(/^(\s*)"(\d+)":\s*(.+)$/);
-            if (currentMatch && currentMatch[1] === indent && currentMatch[2] && currentMatch[3]) {
-                const index = parseInt(currentMatch[2]);
-                let char = currentMatch[3];
-                if (char && char.startsWith('"') && char.endsWith('"')) {
-                    char = char.slice(1, -1);
-                }
-                charMappings.push({ index, char });
-                j++;
-            }
-            else {
-                break;
-            }
-        }
-        if (charMappings.length > 3) {
-            charMappings.sort((a, b) => a.index - b.index);
-            const reconstructed = charMappings.map((m) => m.char).join('');
-            if (reconstructed.includes('{{') && reconstructed.includes('}}')) {
-                return { reconstructed: `${indent}${reconstructed}`, nextIndex: j };
-            }
-        }
-        return { nextIndex: j };
-    }
-    applyHelmTemplateReplacements(processed) {
-        processed = this.fixConditionalBlocks(processed);
-        processed = this.fixPipeExpressions(processed);
-        processed = this.fixNestedQuotes(processed);
-        processed = this.cleanupArtifacts(processed);
-        processed = this.removeHelmExpressionQuotes(processed);
-        return processed;
-    }
-    fixIncludeStatements(processed) {
-        processed = processed.replace(/\{\{ include \\"([^"]+)\\" \. \| nindent (\d+) \}\}/g, '{{ include "$1" . | nindent $2 }}');
-        processed = processed.replace(/\{\{ include \\"([^"]+)\\" \. \}\}/g, '{{ include "$1" . }}');
-        return processed;
-    }
-    fixFunctionCalls(processed) {
-        return processed.replace(/\{\{ (\w+) \\"([^"]*)\\" ([^}]*) \}\}/g, '{{ $1 "$2" $3 }}');
-    }
-    fixChartReferences(processed) {
-        return processed.replace(/\{\{ \.Chart\.(\w+) \| replace \\"([^"]*)\\" \\"([^"]*)\\" ([^}]*) \}\}/g, '{{ .Chart.$1 | replace "$2" "$3" $4 }}');
-    }
-    removeHelmExpressionQuotes(processed) {
-        const HELM_EXPRESSION_REPLACEMENT = '$1$2: {{$3}}';
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\|\s*(?:int|float|bool|number)[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(port):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(port\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(service\.port):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(backend\.service\.port\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(spec\.port):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]*\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(replicas):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(targetPort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(nodePort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(containerPort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(hostPort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(weight):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(priority):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(timeoutSeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(periodSeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(successThreshold):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(failureThreshold):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(initialDelaySeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(terminationGracePeriodSeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(activeDeadlineSeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(backoffLimit):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(parallelism):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(completions):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(revisionHistoryLimit):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(progressDeadlineSeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(minReadySeconds):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(maxUnavailable):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(maxSurge):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(cpu):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(memory):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(enabled):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(create):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(allow):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(disable):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(force):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(required):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(optional):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(readOnly):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(runAsNonRoot):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(privileged):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(allowPrivilegeEscalation):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)(readOnlyRootFilesystem):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*true[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*false[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\d+[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\beq\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\bne\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\blt\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\ble\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\bgt\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\bge\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\band\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\bor\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\bnot\b[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*[+][^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*[-][^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*[*][^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/:\s*"([^"]*\{\{[^}]+\}\}[^"]*)"/g, ': $1');
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"(true|false)"$/gm, '$1$2: $3');
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"(-?\d+)"$/gm, '$1$2: $3');
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"(-?\d+\.\d+)"$/gm, '$1$2: $3');
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"(-?\d+\.?\d*[eE][+-]?\d+)"$/gm, '$1$2: $3');
-        processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        processed = processed.replace(/"\{\{([^}]*)\}\}"/g, '{{$1}}');
-        processed = processed.replace(/^(\s*)-\s*"\{\{([^}]*)\}\}"/gm, '$1- {{$2}}');
-        return processed;
-    }
-    fixConditionalBlocks(processed) {
-        return processed.replace(/"\{\{-\s*(if|with|range)([^}]*)\}\}([^"]*)\{\{-\s*end\s*\}\}"/g, '{{- $1$2}}$3{{- end }}');
-    }
-    fixPipeExpressions(processed) {
-        return processed.replace(/"\{\{([^}]*\|[^}]*)\}\}"/g, '{{$1}}');
-    }
-    fixNestedQuotes(processed) {
-        return processed.replace(/\{\{([^}]*)\\"([^"]*)\\"([^}]*)\}\}/g, '{{$1"$2"$3}}');
-    }
-    cleanupArtifacts(processed) {
-        processed = processed.replace(/": "\.nan"/g, ': .nan');
-        processed = processed.replace(/: \{\{([^}]+)\}\}$/gm, ': {{$1}}');
-        return processed;
-    }
     write(outDir) {
         const timer = this.logger.time('chart_write');
         this.logger.info('Starting chart write operation', {

package/dist/lib/templates/flexible-subchart.js

@@ -107,10 +107,10 @@ export function createFlexibleSubchart(scope, id, config) {
 }
 export function generateFlexibleSubchartTemplate(name) {
     return `import { App } from 'cdk8s';
-import { Rutter } from 'timonel';
+import { Rutter, helmInclude, helmIf, helmWith, createHelmExpression as helm } from 'timonel';
 
 /**
- * Creates a new chart with simple Rutter implementation
+ * Creates a new chart with type-safe Helm helpers
  * @returns Rutter instance for Helm chart generation
  * @since 2.11.0
  */
@@ -126,45 +126,43 @@ export default function createChart() {
     scope: app,
     defaultValues: {
       appName: '${name}',
-      image: 'nginx:latest',
+      image: {
+        repository: 'nginx',
+        tag: 'latest'
+      },
       port: 80,
       replicas: 1,
     },
   });
 
-  // Add simple deployment
+  // Add Deployment with type-safe helpers
   rutter.addManifest({
     apiVersion: 'apps/v1',
     kind: 'Deployment',
     metadata: { 
-      name: '${name}',
-      labels: {
-        'app.kubernetes.io/name': '${name}'
-      }
+      name: helmInclude('chart.fullname', '.'),
+      labels: helmInclude('chart.labels', '.', { pipe: 'nindent 4' })
     },
     spec: {
-      replicas: 1,
+      replicas: helmIf('.Values.autoscaling.enabled', '{{ .Values.replicas }}', '1'),
       selector: {
-        matchLabels: {
-          'app.kubernetes.io/name': '${name}'
-        }
+        matchLabels: helmInclude('chart.selectorLabels', '.', { pipe: 'nindent 6' })
       },
       template: {
         metadata: {
-          labels: {
-            'app.kubernetes.io/name': '${name}'
-          }
+          labels: helmInclude('chart.selectorLabels', '.', { pipe: 'nindent 8' }),
+          annotations: helmWith('.Values.podAnnotations', helm('{{- toYaml . | nindent 8 }}'))
         },
         spec: {
           containers: [{
             name: '${name}',
-            image: 'nginx:latest',
+            image: helm('{{ .Values.image.repository }}:{{ .Values.image.tag }}'),
             ports: [{
-              containerPort: 80
+              containerPort: helm('{{ .Values.port }}')
             }],
             env: [
-              { name: 'APP_NAME', value: '${name}' },
-              { name: 'PORT', value: '80' }
+              { name: 'APP_NAME', value: helm('{{ .Values.appName }}') },
+              { name: 'PORT', value: helm('{{ .Values.port | toString }}') }
             ]
           }]
         }
@@ -172,27 +170,23 @@ export default function createChart() {
     }
   }, 'deployment');
 
-  // Add Service
+  // Add Service with type-safe helpers
   rutter.addManifest({
     apiVersion: 'v1',
     kind: 'Service',
     metadata: {
-      name: '${name}',
-      labels: {
-        'app.kubernetes.io/name': '${name}'
-      }
+      name: helmInclude('chart.fullname', '.'),
+      labels: helmInclude('chart.labels', '.', { pipe: 'nindent 4' })
     },
     spec: {
       type: 'ClusterIP',
       ports: [{
-        port: 80,
-        targetPort: 80,
+        port: helm('{{ .Values.port }}'),
+        targetPort: helm('{{ .Values.port }}'),
         protocol: 'TCP',
         name: 'http'
       }],
-      selector: {
-        'app.kubernetes.io/name': '${name}'
-      }
+      selector: helmInclude('chart.selectorLabels', '.', { pipe: 'nindent 4' })
     }
   }, 'service');
 

package/dist/lib/templates/umbrella-chart.js

@@ -1,16 +1,16 @@
 import { writeFileSync, mkdirSync, existsSync, copyFileSync, readdirSync, rmSync } from 'fs';
 import { join } from 'path';
-import * as jsYaml from 'js-yaml';
+import { parse } from 'yaml';
 import { App, Chart, ApiObject } from 'cdk8s';
 import { dumpHelmAwareYaml } from '../utils/helmYamlSerializer.js';
 import { generateHelpersTemplate } from '../utils/helmHelpers.js';
 import { createFlexibleSubchart } from './flexible-subchart.js';
 export function generateUmbrellaChart(name) {
     return `import { App } from 'cdk8s';
-import { Rutter } from 'timonel';
+import { Rutter, helmInclude, helmIf, helmWith, createHelmExpression as helm } from 'timonel';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import * as jsYaml from 'js-yaml';
+import { parse, stringify } from 'yaml';
 // Import subcharts - add your subchart imports here
 
 type SynthMode = 'dependencies' | 'inline';
@@ -42,7 +42,7 @@ function readYamlFile(filePath: string): Record<string, unknown> {
   if (!existsSync(filePath)) {
     return {};
   }
-  const content = jsYaml.load(readFileSync(filePath, 'utf8'));
+  const content = parse(readFileSync(filePath, 'utf8'));
   return content && typeof content === 'object' ? (content as Record<string, unknown>) : {};
 }
 
@@ -147,8 +147,8 @@ export function synth(outDir: string, options?: SynthOptions) {
     });
   }
 
-  writeFileSync(chartPath, jsYaml.dump(chartDoc));
-  writeFileSync(valuesPath, jsYaml.dump(valuesDoc));
+  writeFileSync(chartPath, stringify(chartDoc));
+  writeFileSync(valuesPath, stringify(valuesDoc));
 
   app.synth();
 
@@ -327,7 +327,7 @@ export class UmbrellaChartTemplate extends Chart {
         const assets = getAssets?.() || [];
         assets.forEach((asset, assetIndex) => {
             try {
-                const manifest = jsYaml.load(asset.yaml);
+                const manifest = parse(asset.yaml);
                 if (manifest?.apiVersion && manifest?.kind) {
                     new ApiObject(flexibleSubchart, `${String(manifest.kind).toLowerCase()}-${assetIndex}`, {
                         apiVersion: String(manifest.apiVersion),

package/dist/lib/utils/helmConstructSerializer.d.ts

@@ -0,0 +1,3 @@
+import type { HelmConstruct, HelmContent } from './helmControlStructures.js';
+export declare function serializeHelmConstruct(construct: HelmConstruct, indent?: number): string;
+export declare function serializeHelmContent(content: HelmContent, indent?: number): string;

package/dist/lib/utils/helmConstructSerializer.js

@@ -0,0 +1,61 @@
+import { isHelmConstruct } from './helmControlStructures.js';
+export function serializeHelmConstruct(construct, indent = 0) {
+    const trimLeft = construct.options?.trimLeft ?? true;
+    const trimRight = construct.options?.trimRight ?? true;
+    const openTag = `{{${trimLeft ? '-' : ''} `;
+    const closeTag = ` ${trimRight ? '-' : ''}}}`;
+    switch (construct.type) {
+        case 'if': {
+            const data = construct.data;
+            let result = `${openTag}if ${data.condition}${closeTag}\n`;
+            result += serializeHelmContent(data.then, indent);
+            if (data.else !== undefined) {
+                result += `\n${openTag}else${closeTag}\n`;
+                result += serializeHelmContent(data.else, indent);
+            }
+            result += `\n${openTag}end${closeTag}`;
+            return result;
+        }
+        default:
+            throw new Error(`Unknown Helm construct type: ${construct.type}`);
+    }
+}
+export function serializeHelmContent(content, indent = 0) {
+    const indentStr = '  '.repeat(indent);
+    if (isHelmConstruct(content)) {
+        return serializeHelmConstruct(content, indent);
+    }
+    if (content === null || content === undefined) {
+        return '';
+    }
+    if (typeof content === 'string' || typeof content === 'number' || typeof content === 'boolean') {
+        return String(content);
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map((item) => {
+            if (isHelmConstruct(item)) {
+                return serializeHelmConstruct(item, indent);
+            }
+            return serializeHelmContent(item, indent);
+        })
+            .join('\n');
+    }
+    if (typeof content === 'object') {
+        const lines = [];
+        for (const [key, value] of Object.entries(content)) {
+            if (isHelmConstruct(value)) {
+                lines.push(`${indentStr}${key}: ${serializeHelmConstruct(value, indent + 1)}`);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                lines.push(`${indentStr}${key}:`);
+                lines.push(serializeHelmContent(value, indent + 1));
+            }
+            else {
+                lines.push(`${indentStr}${key}: ${value}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    return '';
+}

package/dist/lib/utils/helmControlStructures.d.ts

@@ -0,0 +1,34 @@
+export interface HelmConstruct {
+    __helmConstruct: true;
+    type: 'if' | 'range' | 'with' | 'include' | 'define' | 'var' | 'block' | 'comment' | 'fragment';
+    data: unknown;
+    options?: {
+        trimLeft?: boolean;
+        trimRight?: boolean;
+    };
+}
+export declare function helmFragment(...contents: HelmContent[]): HelmConstruct;
+export interface HelmExpression {
+    __helmExpression: true;
+    value: string;
+}
+export declare function createHelmExpression(value: string): HelmExpression;
+export declare function isHelmExpression(value: unknown): value is HelmExpression;
+export declare function helmRange(vars: string, collection: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function helmWith(scope: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function helmInclude(templateName: string, scope?: string, options?: {
+    pipe?: string;
+} & HelmWhitespaceOptions): HelmConstruct;
+export declare function helmDefine(name: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function helmVar(name: string, value: string, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function helmBlock(name: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function helmComment(text: string): HelmConstruct;
+export type HelmContent = string | number | boolean | null | undefined | HelmConstruct | HelmExpression | {
+    [key: string]: HelmContent;
+} | HelmContent[];
+export interface HelmWhitespaceOptions {
+    trimLeft?: boolean;
+    trimRight?: boolean;
+}
+export declare function helmIf(condition: string, thenContent: HelmContent, elseContent?: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+export declare function isHelmConstruct(value: unknown): value is HelmConstruct;

package/dist/lib/utils/helmControlStructures.js

@@ -0,0 +1,112 @@
+export function helmFragment(...contents) {
+    return {
+        __helmConstruct: true,
+        type: 'fragment',
+        data: contents,
+    };
+}
+export function createHelmExpression(value) {
+    return {
+        __helmExpression: true,
+        value,
+    };
+}
+export function isHelmExpression(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__helmExpression' in value &&
+        value.__helmExpression === true);
+}
+export function helmRange(vars, collection, content, options) {
+    return {
+        __helmConstruct: true,
+        type: 'range',
+        data: {
+            vars,
+            collection,
+            content,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmWith(scope, content, options) {
+    return {
+        __helmConstruct: true,
+        type: 'with',
+        data: {
+            scope,
+            content,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmInclude(templateName, scope = '.', options) {
+    return {
+        __helmConstruct: true,
+        type: 'include',
+        data: {
+            templateName,
+            scope,
+            pipe: options?.pipe,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmDefine(name, content, options) {
+    return {
+        __helmConstruct: true,
+        type: 'define',
+        data: {
+            name,
+            content,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmVar(name, value, options) {
+    return {
+        __helmConstruct: true,
+        type: 'var',
+        data: {
+            name,
+            value,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmBlock(name, content, options) {
+    return {
+        __helmConstruct: true,
+        type: 'block',
+        data: {
+            name,
+            content,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function helmComment(text) {
+    return {
+        __helmConstruct: true,
+        type: 'comment',
+        data: { text },
+    };
+}
+export function helmIf(condition, thenContent, elseContent, options) {
+    return {
+        __helmConstruct: true,
+        type: 'if',
+        data: {
+            condition,
+            then: thenContent,
+            else: elseContent,
+        },
+        ...(options ? { options } : {}),
+    };
+}
+export function isHelmConstruct(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__helmConstruct' in value &&
+        value.__helmConstruct === true);
+}

package/dist/lib/utils/helmYamlSerializer.d.ts

@@ -1,26 +1,12 @@
-import * as jsYaml from 'js-yaml';
-type HelmExpressionType = 'block' | 'nested' | 'comment' | 'action-trimmed' | 'raw' | 'include-context' | 'generic';
-interface HelmExpressionMatch {
-    type: HelmExpressionType;
-    expression: string;
-    start: number;
-    end: number;
-}
-export interface HelmExpression {
-    __helmExpression: true;
-    value: string;
-}
-declare function createHelmExpression(value: string): HelmExpression;
-declare function isHelmExpression(value: unknown): value is HelmExpression;
-declare function detectHelmExpressions(str: string): HelmExpressionMatch[];
-declare function preprocessHelmExpressions(obj: unknown, depth?: number): unknown;
-declare function postProcessHelmExpressions(yaml: string): string;
-export declare function dumpHelmAwareYaml(obj: unknown, options?: jsYaml.DumpOptions): string;
+export declare function dumpHelmAwareYaml(obj: unknown, options?: {
+    lineWidth?: number;
+}): string;
 export declare function stringify(obj: unknown, options?: {
     lineWidth?: number;
     doubleQuotedAsJSON?: boolean;
     simpleKeys?: boolean;
 }): string;
+type HelmExpressionType = 'block' | 'nested' | 'comment' | 'action-trimmed' | 'raw' | 'include-context' | 'generic';
 export interface HelmValidationError {
     type: 'syntax' | 'semantic' | 'reference' | 'type';
     message: string;
@@ -48,13 +34,7 @@ export declare function parseHelmExpressions(content: string): Array<{
     endLine: number;
     endCol: number;
 }>;
-export interface PrettifyOptions {
-    indentSize?: number;
-    alignExpressions?: boolean;
-    preserveComments?: boolean;
-    maxLineWidth?: number;
-    sortKeys?: boolean;
-    groupHelpers?: boolean;
-}
-export declare function prettifyHelmTemplate(yaml: string, options?: PrettifyOptions): string;
-export { createHelmExpression, isHelmExpression, detectHelmExpressions, preprocessHelmExpressions, postProcessHelmExpressions, };
+export declare function detectHelmExpressions(str: string): unknown[];
+export declare function preprocessHelmExpressions(obj: unknown): unknown;
+export declare function postProcessHelmExpressions(yaml: string): string;
+export {};

package/dist/lib/utils/helmYamlSerializer.js

@@ -1,111 +1,184 @@
-import * as jsYaml from 'js-yaml';
-const _HELM_EXPRESSION_PATTERNS = [
-    /\{\{-?\s*define\s+[^}]+\s*-?\}\}[\s\S]*?\{\{-?\s*end\s*-?\}\}/g,
-    /\{\{[^}]*\{\{[^}]*\}\}[^}]*\}\}/g,
-    /\{\{\/\*[\s\S]*?\*\/\}\}/g,
-    /\{\{-?[\s\S]*?-?\}\}/g,
-];
-const COMPILED_PATTERNS = [
-    { regex: /\{\{-?\s*define\s+[^}]+\s*-?\}\}[\s\S]*?\{\{-?\s*end\s*-?\}\}/g, type: 'block' },
-    { regex: /\{\{[^}]*\{\{[^}]*\}\}[^}]*\}\}/g, type: 'nested' },
-    { regex: /\{\{\/\*[\s\S]*?\*\/\}\}/g, type: 'comment' },
-    { regex: /\{\{-?[\s\S]*?-?\}\}/g, type: 'action-trimmed' },
-    { regex: /\{\{`[\s\S]*?`\}\}/g, type: 'raw' },
-    { regex: /\{\{\s*include\s+"[^"]+"\s+[^}]+\s*\}\}/g, type: 'include-context' },
-];
-function createHelmExpression(value) {
-    return {
-        __helmExpression: true,
-        value,
-    };
-}
-function isHelmExpression(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        '__helmExpression' in value &&
-        value.__helmExpression === true);
+import { Document, Scalar, isMap, isScalar, visit } from 'yaml';
+import { isHelmConstruct, isHelmExpression, createHelmExpression, } from './helmControlStructures.js';
+function serializeElseIfChain(elseContent, openTag, closeTag) {
+    let result = '';
+    let currentElse = elseContent;
+    if (isHelmConstruct(currentElse) && currentElse.type === 'if') {
+        while (isHelmConstruct(currentElse) && currentElse.type === 'if') {
+            const elseIfData = currentElse.data;
+            result += `\n${openTag}else if ${elseIfData.condition}${closeTag}\n`;
+            result += serializeHelmContent(elseIfData.then);
+            currentElse = elseIfData.else;
+        }
+    }
+    return { result, remainingElse: currentElse };
 }
-function detectHelmExpressions(str) {
-    const matches = [];
-    for (const { regex, type } of COMPILED_PATTERNS) {
-        regex.lastIndex = 0;
-        let result;
-        while ((result = regex.exec(str)) !== null) {
-            matches.push({
-                type,
-                expression: result[0],
-                start: result.index,
-                end: result.index + result[0].length,
-            });
-            if (result.index === regex.lastIndex)
-                regex.lastIndex++;
+function serializeHelmConstruct(construct) {
+    const trimLeft = construct.options?.trimLeft ?? true;
+    const trimRight = construct.options?.trimRight ?? true;
+    const openTag = `{{${trimLeft ? '-' : ''} `;
+    const closeTag = ` ${trimRight ? '-' : ''}}}`;
+    switch (construct.type) {
+        case 'if': {
+            const data = construct.data;
+            let result = `${openTag}if ${data.condition}${closeTag}\n`;
+            result += serializeHelmContent(data.then);
+            if (data.else !== undefined) {
+                const { result: elseIfResult, remainingElse } = serializeElseIfChain(data.else, openTag, closeTag);
+                result += elseIfResult;
+                if (remainingElse !== undefined) {
+                    result += `\n${openTag}else${closeTag}\n`;
+                    result += serializeHelmContent(remainingElse);
+                }
+            }
+            result += `\n${openTag}end${closeTag}`;
+            return result;
+        }
+        case 'fragment': {
+            const data = construct.data;
+            return data.map((item) => serializeHelmContent(item)).join('\n');
+        }
+        case 'range': {
+            const data = construct.data;
+            let result = `${openTag}range ${data.vars} := ${data.collection}${closeTag}\n`;
+            result += serializeHelmContent(data.content);
+            result += `\n${openTag}end${closeTag}`;
+            return result;
+        }
+        case 'with': {
+            const data = construct.data;
+            let result = `${openTag}with ${data.scope}${closeTag}\n`;
+            result += serializeHelmContent(data.content);
+            result += `\n${openTag}end${closeTag}`;
+            return result;
         }
+        case 'include': {
+            const data = construct.data;
+            let result = `${openTag}include "${data.templateName}" ${data.scope}`;
+            if (data.pipe) {
+                result += ` | ${data.pipe}`;
+            }
+            result += `${closeTag}`;
+            return result;
+        }
+        case 'define': {
+            const data = construct.data;
+            let result = `${openTag}define "${data.name}"${closeTag}\n`;
+            result += serializeHelmContent(data.content);
+            result += `\n${openTag}end${closeTag}`;
+            return result;
+        }
+        case 'var': {
+            const data = construct.data;
+            return `${openTag}${data.name} := ${data.value}${closeTag}`;
+        }
+        case 'block': {
+            const data = construct.data;
+            let result = `${openTag}block "${data.name}" .${closeTag}\n`;
+            result += serializeHelmContent(data.content);
+            result += `\n${openTag}end${closeTag}`;
+            return result;
+        }
+        case 'comment': {
+            const data = construct.data;
+            return `{{/* ${data.text} */}}`;
+        }
+        default:
+            throw new Error(`Unknown Helm construct type: ${construct.type}`);
     }
-    return matches.sort((a, b) => a.start - b.start);
 }
-function preprocessHelmExpressions(obj, depth = 0) {
-    if (depth > 100) {
-        throw new Error('Maximum recursion depth exceeded during Helm preprocessing');
+function serializeHelmContent(content) {
+    if (isHelmConstruct(content)) {
+        return serializeHelmConstruct(content);
     }
-    if (typeof obj === 'string') {
-        if (detectHelmExpressions(obj).length > 0) {
-            return createHelmExpression(obj);
-        }
-        return obj;
+    if (isHelmExpression(content)) {
+        return content.value;
+    }
+    if (content === null || content === undefined) {
+        return '';
+    }
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (typeof content === 'number' || typeof content === 'boolean') {
+        return String(content);
+    }
+    if (typeof content === 'object') {
+        const doc = new Document(content);
+        let yaml = doc.toString({ lineWidth: 0 });
+        yaml = yaml.trim();
+        return yaml;
+    }
+    return '';
+}
+function preprocessHelmConstructs(obj) {
+    if (isHelmConstruct(obj)) {
+        const helmTemplate = serializeHelmConstruct(obj);
+        return createHelmExpression(helmTemplate);
     }
     if (Array.isArray(obj)) {
-        return obj.map((item) => preprocessHelmExpressions(item, depth + 1));
+        return obj.map((item) => preprocessHelmConstructs(item));
     }
-    if (typeof obj === 'object' && obj !== null) {
+    if (obj !== null && typeof obj === 'object') {
+        if (isHelmExpression(obj)) {
+            return obj;
+        }
         const result = {};
         for (const [key, value] of Object.entries(obj)) {
-            Object.defineProperty(result, key, {
-                value: preprocessHelmExpressions(value, depth + 1),
-                writable: true,
-                enumerable: true,
-                configurable: true,
-            });
+            result[key] = preprocessHelmConstructs(value);
         }
         return result;
     }
     return obj;
 }
-function helmAwareReplacer(key, value) {
-    if (isHelmExpression(value)) {
-        return value.value;
-    }
-    return value;
-}
-function postProcessHelmExpressions(yaml) {
-    let processed = yaml;
-    processed = processed.replace(/'(\{\{[^}]*\}\})'/g, '$1');
-    processed = processed.replace(/"(\{\{[^}]*\}\})"/g, '$1');
-    processed = processed.replace(/'(\{\{[^}]*\\"[^}]*\}\})'/g, '$1');
-    processed = processed.replace(/"(\{\{[^}]*\\"[^}]*\}\})"/g, '$1');
-    processed = processed.replace(/\\(\{\{[^}]+\}\})/g, '$1');
-    return processed;
-}
 export function dumpHelmAwareYaml(obj, options = {}) {
-    const preprocessed = preprocessHelmExpressions(obj);
-    const dumpOptions = {
-        forceQuotes: false,
-        lineWidth: options.lineWidth ?? 0,
-        flowLevel: options.flowLevel ?? -1,
-        replacer: helmAwareReplacer,
-        ...options,
-    };
-    let yamlOutput = jsYaml.dump(preprocessed, dumpOptions);
-    yamlOutput = postProcessHelmExpressions(yamlOutput);
-    return yamlOutput;
+    const preprocessed = preprocessHelmConstructs(obj);
+    const doc = new Document(preprocessed);
+    visit(doc, (_key, node) => {
+        if (isMap(node)) {
+            const isHelmExpr = node.items.some((pair) => isScalar(pair.key) &&
+                pair.key.value === '__helmExpression' &&
+                isScalar(pair.value) &&
+                pair.value.value === true);
+            if (isHelmExpr) {
+                const valuePair = node.items.find((pair) => isScalar(pair.key) && pair.key.value === 'value');
+                if (valuePair && isScalar(valuePair.value)) {
+                    const value = String(valuePair.value.value);
+                    const scalar = new Scalar(value);
+                    if (value.trim().startsWith('{{') && value.includes('\n')) {
+                        scalar.type = 'BLOCK_LITERAL';
+                    }
+                    else {
+                        scalar.type = 'QUOTE_DOUBLE';
+                    }
+                    return scalar;
+                }
+            }
+        }
+        return undefined;
+    });
+    const toStringOptions = {};
+    if (options.lineWidth !== undefined) {
+        toStringOptions.lineWidth = options.lineWidth;
+    }
+    let result = doc.toString(toStringOptions);
+    result = result.replace(/\\"/g, '"');
+    result = result.replace(/\\\\/g, '');
+    result = result.replace(/:\s*\|[-+]?\s*\n(\s*\{\{)/g, ':\n$1');
+    result = result.replace(/"(\{\{[\s\S]*?\}\})"/g, '$1');
+    return result;
 }
 export function stringify(obj, options = {}) {
-    const jsYamlOptions = {
-        lineWidth: options.lineWidth ?? 0,
-        quotingType: options.doubleQuotedAsJSON ? '"' : "'",
-        forceQuotes: options.doubleQuotedAsJSON,
-    };
-    return dumpHelmAwareYaml(obj, jsYamlOptions);
+    return dumpHelmAwareYaml(obj, options.lineWidth !== undefined ? { lineWidth: options.lineWidth } : {});
 }
+const COMPILED_PATTERNS = [
+    { regex: /\{\{-?\s*define\s+[^}]+\s*-?\}\}[\s\S]*?\{\{-?\s*end\s*-?\}\}/g, type: 'block' },
+    { regex: /\{\{[^}]*\{\{[^}]*\}\}[^}]*\}\}/g, type: 'nested' },
+    { regex: /\{\{\/\*[\s\S]*?\*\/\}\}/g, type: 'comment' },
+    { regex: /\{\{-?[\s\S]*?-?\}\}/g, type: 'action-trimmed' },
+    { regex: /\{\{`[\s\S]*?`\}\}/g, type: 'raw' },
+    { regex: /\{\{\s*include\s+"[^"]+"\s+[^}]+\s*\}\}/g, type: 'include-context' },
+];
 export function validateHelmYaml(yaml) {
     const errors = [];
     const warnings = [];
@@ -277,120 +350,12 @@ function calculateComplexity(expressions) {
     }
     return score;
 }
-export function prettifyHelmTemplate(yaml, options = {}) {
-    const { indentSize = 2, alignExpressions = true, preserveComments: _preserveComments = true, maxLineWidth = 120, sortKeys = false, groupHelpers = true, } = options;
-    let formatted = yaml;
-    if (groupHelpers) {
-        formatted = groupHelmHelpers(formatted);
-    }
-    if (alignExpressions) {
-        formatted = alignTemplateExpressions(formatted, indentSize);
-    }
-    formatted = formatConditionalBlocks(formatted, indentSize);
-    formatted = formatLoopBlocks(formatted, indentSize);
-    formatted = wrapLongLines(formatted, maxLineWidth);
-    if (sortKeys) {
-        formatted = sortYamlKeys(formatted);
-    }
-    return formatted;
+export function detectHelmExpressions(str) {
+    return parseHelmExpressions(str);
 }
-function alignTemplateExpressions(yaml, _indentSize) {
-    const lines = yaml.split('\n');
-    const aligned = [];
-    for (const line of lines) {
-        const expressions = line.match(/\{\{[^}]*\}\}/g);
-        if (expressions && expressions.length > 1) {
-            const baseIndent = (line.match(/^\s*/) || [''])[0];
-            const content = line.trim();
-            const parts = content.split(/(\{\{[^}]*\}\})/);
-            let alignedLine = baseIndent;
-            for (let i = 0; i < parts.length; i++) {
-                alignedLine += parts[i] || '';
-                const nextPart = parts[i + 1];
-                if (i < parts.length - 1 && nextPart && nextPart.startsWith('{{')) {
-                    alignedLine += ' ';
-                }
-            }
-            aligned.push(alignedLine);
-        }
-        else {
-            aligned.push(line);
-        }
-    }
-    return aligned.join('\n');
-}
-function groupHelmHelpers(yaml) {
-    const lines = yaml.split('\n');
-    const groups = {
-        comments: [],
-        definitions: [],
-        conditionals: [],
-        loops: [],
-        other: [],
-    };
-    for (const line of lines) {
-        if (line.includes('{{/*')) {
-            groups.comments.push(line);
-        }
-        else if (line.includes('{{- define')) {
-            groups.definitions.push(line);
-        }
-        else if (/\{\{\s*(if|else|end)\s/.test(line)) {
-            groups.conditionals.push(line);
-        }
-        else if (/\{\{\s*(range|with)\s/.test(line)) {
-            groups.loops.push(line);
-        }
-        else {
-            groups.other.push(line);
-        }
-    }
-    return [
-        ...groups.comments,
-        ...groups.definitions,
-        ...groups.conditionals,
-        ...groups.loops,
-        ...groups.other,
-    ].join('\n');
-}
-function formatConditionalBlocks(yaml, indentSize) {
-    const indent = ' '.repeat(indentSize);
-    return yaml
-        .replace(/(\{\{\s*if\s+[^}]+\}\})/g, '$1\n' + indent)
-        .replace(/(\{\{\s*else\s*\}\})/g, '$1\n' + indent)
-        .replace(/(\{\{\s*end\s*\}\})/g, '\n$1');
-}
-function formatLoopBlocks(yaml, indentSize) {
-    const indent = ' '.repeat(indentSize);
-    return yaml
-        .replace(/(\{\{\s*range\s+[^}]+\}\})/g, '$1\n' + indent)
-        .replace(/(\{\{\s*with\s+[^}]+\}\})/g, '$1\n' + indent);
-}
-function wrapLongLines(yaml, maxLineWidth) {
-    if (maxLineWidth <= 0)
-        return yaml;
-    const lines = yaml.split('\n');
-    const wrapped = [];
-    for (const line of lines) {
-        if (line.length <= maxLineWidth) {
-            wrapped.push(line);
-            continue;
-        }
-        let remaining = line;
-        while (remaining.length > maxLineWidth) {
-            let wrapIndex = remaining.lastIndexOf(' ', maxLineWidth);
-            if (wrapIndex === -1)
-                wrapIndex = maxLineWidth;
-            wrapped.push(remaining.slice(0, wrapIndex));
-            remaining = remaining.slice(wrapIndex).trim();
-        }
-        if (remaining.length > 0) {
-            wrapped.push(remaining);
-        }
-    }
-    return wrapped.join('\n');
+export function preprocessHelmExpressions(obj) {
+    return preprocessHelmConstructs(obj);
 }
-function sortYamlKeys(yaml) {
+export function postProcessHelmExpressions(yaml) {
     return yaml;
 }
-export { createHelmExpression, isHelmExpression, detectHelmExpressions, preprocessHelmExpressions, postProcessHelmExpressions, };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "timonel",
   "type": "module",
-  "version": "2.13.0-beta.1",
+  "version": "2.14.0-beta.1",
   "description": "Timonel: programmatic Helm chart generator using cdk8s (TypeScript)",
   "bin": {
     "timonel": "dist/cli.js",
@@ -12,18 +12,27 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./lib/helm": {
       "types": "./dist/lib/helm.d.ts",
+      "import": "./dist/lib/helm.js",
       "default": "./dist/lib/helm.js"
     },
+    "./lib/utils/helmControlStructures": {
+      "types": "./dist/lib/utils/helmControlStructures.d.ts",
+      "import": "./dist/lib/utils/helmControlStructures.js",
+      "default": "./dist/lib/utils/helmControlStructures.js"
+    },
     "./lib/utils/logger": {
       "types": "./dist/lib/utils/logger.d.ts",
+      "import": "./dist/lib/utils/logger.js",
       "default": "./dist/lib/utils/logger.js"
     },
     "./lib/utils/helmYamlSerializer": {
       "types": "./dist/lib/utils/helmYamlSerializer.d.ts",
+      "import": "./dist/lib/utils/helmYamlSerializer.js",
       "default": "./dist/lib/utils/helmYamlSerializer.js"
     }
   },
@@ -95,7 +104,6 @@
     "cdk8s-plus-33": "^2.4.6",
     "constructs": "^10.4.3",
     "handlebars": "^4.7.8",
-    "js-yaml": "^4.1.1",
     "pino": "^10.1.0",
     "pino-pretty": "^13.1.2",
     "ts-node": "^10.9.2",
@@ -108,7 +116,6 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.10.1",
     "@typescript-eslint/eslint-plugin": "^8.47.0",
     "@typescript-eslint/parser": "^8.47.0",