timonel 2.8.1 → 2.9.0

package/dist/lib/helm.js

@@ -1,152 +1,33 @@
-/**
- * @fileoverview Helpers to embed Helm template expressions while staying type-safe in TypeScript.
- * We treat Helm placeholders as opaque strings that will be preserved in YAML.
- * @since 0.1.0
- */
 import { SecurityUtils } from './security.js';
-/**
- * Creates a reference to a value in .Values of Helm
- *
- * Generates a Helm template expression that references a value
- * in the chart's values.yaml file using dot notation.
- *
- * @param {string} path - Path to the value using dot notation (e.g., 'image.tag')
- * @returns {string} Helm template expression (e.g., '{{ .Values.image.tag }}')
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const imageTag = valuesRef('image.tag');
- * // Returns: '{{ .Values.image.tag }}'
- *
- * const replicas = valuesRef('deployment.replicas');
- * // Returns: '{{ .Values.deployment.replicas }}'
- * ```
- *
- * @since 0.1.0
- */
 export function valuesRef(path) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
     return `{{ .Values.${path} }}`;
 }
-/**
- * Creates a required reference to a value in .Values of Helm
- *
- * Similar to valuesRef, but uses Helm's 'required' function to
- * ensure the value is present, failing chart rendering if not provided.
- *
- * @param {string} path - Path to the value using dot notation
- * @param {string} [message] - Custom error message if value is missing
- * @returns {string} Helm template expression with required validation
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const dbPassword = requiredValuesRef('database.password', 'Database password is required');
- * // Returns: '{{ required "Database password is required" .Values.database.password }}'
- *
- * const apiKey = requiredValuesRef('api.key');
- * // Returns: '{{ required "api.key is required" .Values.api.key }}'
- * ```
- *
- * @since 0.1.0
- */
 export function requiredValuesRef(path, message) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
     const msg = message ?? `${path} is required`;
-    // Escape quotes and backslashes in message to prevent template injection
     const escapedMsg = msg.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     return `{{ required "${escapedMsg}" .Values.${path} }}`;
 }
-/**
- * Validates Helm template path syntax with enhanced security
- *
- * @private
- * @param {string} path - Path to validate
- * @returns {boolean} True if path is valid for Helm templates
- * @since 0.1.0
- */
 function isValidHelmPath(path) {
-    // Use centralized validation from SecurityUtils
     return SecurityUtils.isValidHelmTemplatePath(path);
 }
-/**
- * Built-in Helm references for release and chart metadata
- *
- * Object containing the most common references to Helm's built-in
- * variables for release and chart information.
- *
- * @namespace helm
- * @since 0.1.0
- *
- * @example
- * ```typescript
- * const deploymentName = `${helm.releaseName}-deployment`;
- * // Uses: '{{ .Release.Name }}-deployment'
- *
- * const version = helm.chartVersion;
- * // Uses: '{{ .Chart.Version }}'
- * ```
- */
 export const helm = {
-    /** Release name: {{ .Release.Name }} */
     releaseName: '{{ .Release.Name }}',
-    /** Chart name: {{ .Chart.Name }} */
     chartName: '{{ .Chart.Name }}',
-    /** Chart version: {{ .Chart.Version }} */
     chartVersion: '{{ .Chart.Version }}',
-    /** Release namespace: {{ .Release.Namespace }} */
     namespace: '{{ .Release.Namespace }}',
 };
-/**
- * Quotes a Helm template expression for safe YAML embedding
- *
- * Ensures Helm template expressions are properly quoted to avoid
- * YAML parsing issues when the expression contains special characters.
- *
- * @param {string} expr - Helm template expression to quote
- * @returns {string} Quoted expression if it's a Helm template, otherwise unchanged
- *
- * @example
- * ```typescript
- * const quoted = quote('{{ .Values.image.tag }}');
- * // Returns: "'{{ .Values.image.tag }}'"
- *
- * const normal = quote('nginx:1.21');
- * // Returns: "nginx:1.21"
- * ```
- *
- * @since 0.1.0
- */
 export function quote(expr) {
-    // ensure Helm templates are quoted to avoid YAML parsing issues
     if (expr.startsWith('{{') && expr.endsWith('}}')) {
         return `'${expr}'`;
     }
     return expr;
 }
-/**
- * Indents text by specified number of spaces
- *
- * Helper function that matches Helm's indent function behavior,
- * adding the specified number of spaces to each non-empty line.
- *
- * @param {number} n - Number of spaces to indent
- * @param {string} expr - Text to indent
- * @returns {string} Indented text
- *
- * @example
- * ```typescript
- * const indented = indent(4, 'line1\nline2');
- * // Returns: "    line1\n    line2"
- * ```
- *
- * @since 0.1.0
- */
 export function indent(n, expr) {
     const spaces = ' '.repeat(n);
     return expr
@@ -154,59 +35,17 @@ export function indent(n, expr) {
         .map((l) => (l.trim().length ? spaces + l : l))
         .join('\n');
 }
-/**
- * Inserts a call to a named Helm template using template function
- *
- * @param {string} name - Name of the template to call
- * @param {string} [context='.'] - Context to pass to the template
- * @returns {string} Helm template expression
- *
- * @example
- * ```typescript
- * const tmpl = template('myapp.labels');
- * // Returns: '{{ template "myapp.labels" . }}'
- * ```
- *
- * @since 0.1.0
- */
 export function template(name, context = '.') {
     return `{{ template "${name}" ${context} }}`;
 }
-/**
- * Inserts a call to a named Helm template using include function
- *
- * Preferred over template() as include allows piping and better error handling.
- *
- * @param {string} name - Name of the template to include
- * @param {string} [context='.'] - Context to pass to the template
- * @returns {string} Helm template expression
- *
- * @example
- * ```typescript
- * const tmpl = include('myapp.labels');
- * // Returns: '{{ include "myapp.labels" . }}'
- * ```
- *
- * @since 0.1.0
- */
 export function include(name, context = '.') {
     return `{{ include "${name}" ${context} }}`;
 }
-/**
- * Factory function to create typed Helm value references with reduced code duplication
- * @param path - The path to the value in the Helm values
- * @param type - The expected type of the value
- * @param options - Additional options for reference creation
- * @returns A string that can be used in Helm templates
- * @throws {Error} If the path is invalid
- * @since 1.1.0
- */
 export function createTypedRef(path, type, options = {}) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
     let template = `{{ .Values.${path}`;
-    // Apply type casting based on type
     switch (type) {
         case 'number':
             template += ' | int';
@@ -221,119 +60,31 @@ export function createTypedRef(path, type, options = {}) {
             template += ' | float64';
             break;
     }
-    // Handle default values following Helm best practices
     if (options.withDefault && options.defaultValue !== undefined) {
         const defaultVal = typeof options.defaultValue === 'string' && options.quote
             ? `"${options.defaultValue}"`
             : String(options.defaultValue);
         template += ` | default ${defaultVal}`;
     }
-    // Handle string quoting for security
     if (type === 'string' && options.quote && !options.withDefault) {
         template += ' | quote';
     }
     template += ' }}';
     return template;
 }
-/**
- * Creates a numeric reference from .Values with int cast
- *
- * Generates a Helm template expression that casts the value to integer,
- * truncating any decimal places.
- *
- * @param {string} path - Path to the value using dot notation
- * @param {TypedRefOptions} [options] - Additional options for reference creation
- * @returns {string} Helm template expression with int cast
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const replicas = numberRef('deployment.replicas');
- * // Returns: '{{ .Values.deployment.replicas | int }}'
- * ```
- *
- * @since 0.1.0
- */
 export function numberRef(path, options) {
     return createTypedRef(path, 'number', options);
 }
-/**
- * Creates a boolean reference from .Values with toBool cast
- *
- * @param {string} path - Path to the value using dot notation
- * @param {TypedRefOptions} [options] - Additional options for reference creation
- * @returns {string} Helm template expression with toBool cast
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const enabled = boolRef('feature.enabled');
- * // Returns: '{{ .Values.feature.enabled | toBool }}'
- * ```
- *
- * @since 0.1.0
- */
 export function boolRef(path, options) {
     return createTypedRef(path, 'boolean', options);
 }
-/**
- * Creates a string reference from .Values with toString cast
- *
- * @param {string} path - Path to the value using dot notation
- * @param {TypedRefOptions} [options] - Additional options for reference creation
- * @returns {string} Helm template expression with toString cast
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const version = stringRef('app.version');
- * // Returns: '{{ .Values.app.version | toString }}'
- * ```
- *
- * @since 0.1.0
- */
 export function stringRef(path, options) {
     const defaultOptions = { quote: true, ...options };
     return createTypedRef(path, 'string', defaultOptions);
 }
-/**
- * Creates a float reference from .Values with float64 cast
- *
- * @param {string} path - Path to the value using dot notation
- * @param {TypedRefOptions} [options] - Additional options for reference creation
- * @returns {string} Helm template expression with float64 cast
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const ratio = floatRef('scaling.ratio');
- * // Returns: '{{ .Values.scaling.ratio | float64 }}'
- * ```
- *
- * @since 0.1.0
- */
 export function floatRef(path, options) {
     return createTypedRef(path, 'float', options);
 }
-/**
- * Creates a conditional reference to a value in .Values
- *
- * Generates a Helm template expression that conditionally renders
- * the value only if the condition is truthy.
- *
- * @param {string} path - Path to the value using dot notation
- * @param {string} condition - Path to the condition value
- * @returns {string} Helm template expression with conditional logic
- * @throws {Error} If the path or condition is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const secretName = conditionalRef('database.secretName', 'database.enabled');
- * // Returns: '{{ if .Values.database.enabled }}{{ .Values.database.secretName }}{{ end }}'
- * ```
- *
- * @since 2.6.0
- */
 export function conditionalRef(path, condition) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
@@ -343,165 +94,38 @@ export function conditionalRef(path, condition) {
     }
     return `{{ if .Values.${condition} }}{{ .Values.${path} }}{{ end }}`;
 }
-/**
- * Wraps a complete YAML manifest in a Helm conditional
- *
- * Generates a Helm template that conditionally renders an entire
- * Kubernetes manifest based on a values condition.
- *
- * @param {string} yamlContent - Complete YAML manifest content
- * @param {string} condition - Path to the condition value
- * @returns {string} YAML content wrapped in Helm conditional
- * @throws {Error} If the condition path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const namespaceYaml = `
- * apiVersion: v1
- * kind: Namespace
- * metadata:
- *   name: my-namespace
- * `;
- * const conditionalNamespace = conditionalManifest(namespaceYaml, 'createNamespace');
- * // Returns: '{{ if .Values.createNamespace }}\napiVersion: v1\nkind: Namespace...{{ end }}'
- * ```
- *
- * @since 2.7.4
- */
 export function conditionalManifest(yamlContent, condition) {
     if (!isValidHelmPath(condition)) {
         throw new Error(`Invalid Helm template condition path: ${condition}`);
     }
-    // Remove leading/trailing whitespace and ensure proper formatting
     const cleanYaml = yamlContent.trim();
     return `{{ if .Values.${condition} }}
 ${cleanYaml}
 {{ end }}`;
 }
-/**
- * Creates a reference to a value in .Values with a default fallback
- *
- * Generates a Helm template expression that uses the default filter
- * to provide a fallback value when the path is not set.
- *
- * @param {string} path - Path to the value using dot notation
- * @param {string} defaultValue - Default value to use if path is not set
- * @returns {string} Helm template expression with default fallback
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const image = defaultRef('image.tag', 'latest');
- * // Returns: '{{ .Values.image.tag | default "latest" }}'
- * ```
- *
- * @since 2.6.0
- */
 export function defaultRef(path, defaultValue) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
-    // Escape quotes and backslashes in defaultValue to prevent template injection
     const escapedValue = defaultValue.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     return `{{ .Values.${path} | default "${escapedValue}" }}`;
 }
-/**
- * Creates a base64-encoded reference to a value in .Values
- *
- * Generates a Helm template expression that encodes the value
- * using base64 encoding, useful for secrets and certificates.
- *
- * @param {string} path - Path to the value using dot notation
- * @returns {string} Helm template expression with base64 encoding
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const encodedSecret = base64Ref('secrets.apiKey');
- * // Returns: '{{ .Values.secrets.apiKey | b64enc }}'
- * ```
- *
- * @since 2.6.0
- */
 export function base64Ref(path) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
     return `{{ .Values.${path} | b64enc }}`;
 }
-/**
- * Creates a JSON-serialized reference to a value in .Values
- *
- * Generates a Helm template expression that serializes the value
- * to JSON format, useful for complex configuration objects.
- *
- * @param {string} path - Path to the value using dot notation
- * @returns {string} Helm template expression with JSON serialization
- * @throws {Error} If the path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const configJson = jsonRef('app.config');
- * // Returns: '{{ .Values.app.config | toJson }}'
- * ```
- *
- * @since 2.6.0
- */
 export function jsonRef(path) {
     if (!isValidHelmPath(path)) {
         throw new Error(`Invalid Helm template path: ${path}`);
     }
     return `{{ .Values.${path} | toJson }}`;
 }
-/**
- * Flow Control Functions for Helm Templates
- *
- * These functions provide programmatic access to Helm's flow control structures:
- * if/else, with, and range for conditional logic and iteration.
- *
- * @since 1.4.0
- */
-/**
- * Creates a conditional if block in Helm templates
- *
- * Generates Helm template expressions for conditional logic using if/else/end.
- * Supports complex conditions with comparison operators and pipeline expressions.
- *
- * @param {string} condition - The condition to evaluate (e.g., 'eq .Values.env "production"')
- * @param {string} content - Content to include when condition is true
- * @param {string} [elseContent] - Optional content for else block
- * @returns {string} Complete Helm if/else template block
- * @throws {Error} If condition contains potentially unsafe template expressions
- *
- * @example
- * ```typescript
- * const conditionalConfig = helmIf(
- *   'eq .Values.environment "production"',
- *   'replicas: 3\nresources:\n  limits:\n    memory: "1Gi"',
- *   'replicas: 1\nresources:\n  limits:\n    memory: "512Mi"'
- * );
- * // Returns:
- * // {{- if eq .Values.environment "production" }}
- * // replicas: 3
- * // resources:
- * //   limits:
- * //     memory: "1Gi"
- * // {{- else }}
- * // replicas: 1
- * // resources:
- * //   limits:
- * //     memory: "512Mi"
- * // {{- end }}
- * ```
- *
- * @since 2.8.0
- */
 export function helmIf(condition, content, elseContent) {
-    // Validate condition for basic security
     if (!condition || condition.trim().length === 0) {
         throw new Error('Condition cannot be empty');
     }
-    // Basic validation to prevent template injection
     if (condition.includes('{{') || condition.includes('}}')) {
         throw new Error('Condition should not contain template delimiters');
     }
@@ -512,44 +136,10 @@ export function helmIf(condition, content, elseContent) {
     result += `\n{{- end }}`;
     return result;
 }
-/**
- * Creates a with block for scoped template context
- *
- * Generates Helm template expressions using 'with' to change the template context.
- * Useful for accessing nested values without repeating the full path.
- *
- * @param {string} path - Path to set as new context (e.g., '.Values.database')
- * @param {string} content - Content to render within the new context
- * @param {string} [elseContent] - Optional content when path is empty/nil
- * @returns {string} Complete Helm with/else/end template block
- * @throws {Error} If path is not valid for Helm templates
- *
- * @example
- * ```typescript
- * const dbConfig = helmWith(
- *   '.Values.database',
- *   'host: {{ .host }}\nport: {{ .port }}\nname: {{ .name }}',
- *   'host: "localhost"\nport: 5432\nname: "defaultdb"'
- * );
- * // Returns:
- * // {{- with .Values.database }}
- * // host: {{ .host }}
- * // port: {{ .port }}
- * // name: {{ .name }}
- * // {{- else }}
- * // host: "localhost"
- * // port: 5432
- * // name: "defaultdb"
- * // {{- end }}
- * ```
- *
- * @since 2.8.0
- */
 export function helmWith(path, content, elseContent) {
     if (!path || path.trim().length === 0) {
         throw new Error('Path cannot be empty');
     }
-    // Validate path format
     if (!path.startsWith('.')) {
         throw new Error('Path must start with "." (e.g., ".Values.config")');
     }
@@ -560,48 +150,6 @@ export function helmWith(path, content, elseContent) {
     result += `\n{{- end }}`;
     return result;
 }
-/**
- * Creates a range loop for iterating over collections
- *
- * Generates Helm template expressions using 'range' to iterate over lists, maps, or other collections.
- * Supports both simple iteration and key-value iteration for maps.
- *
- * @param {string} collection - Collection to iterate over (e.g., '.Values.items')
- * @param {string} content - Content template for each iteration
- * @param {object} [options] - Configuration options for the range loop
- * @param {boolean} [options.keyValue=false] - Whether to iterate with key-value pairs
- * @param {string} [options.keyVar='$key'] - Variable name for keys in key-value iteration
- * @param {string} [options.valueVar='$value'] - Variable name for values in key-value iteration
- * @param {string} [options.indexVar='$index'] - Variable name for index in indexed iteration
- * @param {string} [options.itemVar='$item'] - Variable name for items in simple iteration
- * @returns {string} Complete Helm range/end template block
- * @throws {Error} If collection path is not valid
- *
- * @example
- * ```typescript
- * // Simple list iteration
- * const serviceList = helmRange(
- *   '.Values.services',
- *   '- name: {{ .name }}\n  port: {{ .port }}'
- * );
- *
- * // Key-value map iteration
- * const envVars = helmRange(
- *   '.Values.env',
- *   '- name: {{ $key }}\n  value: {{ $value | quote }}',
- *   { keyValue: true }
- * );
- *
- * // Indexed iteration
- * const indexedItems = helmRange(
- *   '.Values.items',
- *   '{{ $index }}: {{ $item }}',
- *   { indexVar: '$i', itemVar: '$val' }
- * );
- * ```
- *
- * @since 2.8.0
- */
 export function helmRange(collection, content, options = {}) {
     if (!collection || collection.trim().length === 0) {
         throw new Error('Collection cannot be empty');
@@ -622,33 +170,6 @@ export function helmRange(collection, content, options = {}) {
     }
     return `${rangeExpression}\n${content}\n{{- end }}`;
 }
-/**
- * Creates a complex conditional with multiple else-if branches
- *
- * Generates Helm template expressions for complex conditional logic with multiple branches.
- * Useful for handling multiple environment configurations or feature flags.
- *
- * @param {Array<{condition: string, content: string}>} branches - Array of condition-content pairs
- * @param {string} [defaultContent] - Default content when no conditions match
- * @returns {string} Complete Helm if/else-if/else/end template block
- * @throws {Error} If branches array is empty or contains invalid conditions
- *
- * @example
- * ```typescript
- * const envConfig = helmIfElseIf([
- *   {
- *     condition: 'eq .Values.environment "production"',
- *     content: 'replicas: 5\nresources.limits.memory: "2Gi"'
- *   },
- *   {
- *     condition: 'eq .Values.environment "staging"',
- *     content: 'replicas: 2\nresources.limits.memory: "1Gi"'
- *   }
- * ], 'replicas: 1\nresources.limits.memory: "512Mi"');
- * ```
- *
- * @since 2.8.0
- */
 export function helmIfElseIf(branches, defaultContent) {
     if (!branches || branches.length === 0) {
         throw new Error('At least one branch is required');
@@ -658,7 +179,6 @@ export function helmIfElseIf(branches, defaultContent) {
         if (!branch.condition || branch.condition.trim().length === 0) {
             throw new Error(`Branch ${index} condition cannot be empty`);
         }
-        // Basic validation to prevent template injection
         if (branch.condition.includes('{{') || branch.condition.includes('}}')) {
             throw new Error(`Branch ${index} condition should not contain template delimiters`);
         }
@@ -671,4 +191,3 @@ export function helmIfElseIf(branches, defaultContent) {
     result += '{{- end }}';
     return result;
 }
-//# sourceMappingURL=helm.js.map