timonel 3.1.1 → 3.1.2

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

@@ -1,33 +1,227 @@
+/**
+ * @fileoverview Helm template control structure helpers
+ * Provides type-safe, composable helpers for Helm template constructs
+ * @since 2.14.0
+ */
+/**
+ * Base interface for all Helm constructs
+ * Used by the serializer to detect and handle Helm template structures
+ */
 export interface HelmConstruct {
     __helmConstruct: true;
     type: 'if' | 'range' | 'with' | 'include' | 'define' | 'var' | 'block' | 'comment' | 'fragment' | 'fieldConditional';
     data: unknown;
     options?: HelmWhitespaceOptions;
 }
+/**
+ * Creates a Helm fragment (composite of multiple contents).
+ * Useful for combining multiple constructs (e.g. multiple if blocks) into a single field value.
+ * @param contents List of Helm content to combine
+ * @returns HelmConstruct of type 'fragment'
+ */
 export declare function helmFragment(...contents: HelmContent[]): HelmConstruct;
+/**
+ * Represents a Helm template expression marker.
+ * Prevents quoting of Helm expressions (legacy concept, now handled via scalar types).
+ * @since 2.9.2
+ */
 export interface HelmExpression {
     __helmExpression: true;
     value: string;
 }
+/**
+ * Creates a Helm expression marker.
+ * @param value Helm template expression string.
+ * @returns Helm expression marker object.
+ * @since 2.9.2
+ */
 export declare function createHelmExpression(value: string): HelmExpression;
+/**
+ * Checks if a value is a Helm expression marker.
+ * @param value Value to check.
+ * @returns True if value is a Helm expression marker.
+ * @since 2.9.2
+ */
 export declare function isHelmExpression(value: unknown): value is HelmExpression;
+/**
+ * Creates a Helm range (iteration) block.
+ *
+ * @param vars - Variable(s) to bind (e.g., 'item', '$key, $value', '$index, $item')
+ * @param collection - Helm expression for the collection to iterate (e.g., '.Values.items')
+ * @param content - Content to repeat for each iteration
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'range'
+ *
+ * helmRange('$key, $value', '.Values.secrets', {
+ *   [helmVar('$key')]: helmVar('$value')]
+ * })
+ */
 export declare function helmRange(vars: string, collection: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm with block (scope/context switching).
+ *
+ * @param scope - Helm expression for the scope to switch to (e.g., '.Values.database')
+ * @param content - Content to execute with the new scope (where '.' refers to the scope)
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'with'
+ *
+ * @example
+ * // Simplify nested object access
+ * helmWith('.Values.database', {
+ *   host: helm('{{ .host }}'),
+ *   port: helm('{{ .port }}'),
+ *   username: helm('{{ .username }}')
+ * })
+ */
 export declare function helmWith(scope: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm include statement (template inclusion).
+ *
+ * @param templateName - Name of the template to include (e.g., 'myapp.labels')
+ * @param scope - Scope to pass to the template (usually '.')
+ * @param pipe - Optional pipe operations (e.g., 'nindent 4', 'quote')
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'include'
+ *
+ * @example
+ * helmInclude('myapp.labels', '.', { pipe: 'nindent 4' })
+ * // Output: {{ include "myapp.labels" . | nindent 4 }}
+ */
 export declare function helmInclude(templateName: string, scope?: string, options?: {
     pipe?: string;
 } & HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm define block (template definition).
+ *
+ * @param name - Name of the template
+ * @param content - Template content
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'define'
+ *
+ * @example
+ * helmDefine('myapp.labels', {
+ *   'app.kubernetes.io/name': helm('{{ .Chart.Name }}'),
+ *   'app.kubernetes.io/instance': helm('{{ .Release.Name }}')
+ * })
+ */
 export declare function helmDefine(name: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm variable assignment.
+ *
+ * @param name - Variable name (with $ prefix)
+ * @param value - Value to assign
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'var'
+ *
+ * @example
+ * helmVar('$fullName', 'include "myapp.fullname" .')
+ * // Output: {{ $fullName := include "myapp.fullname" . }}
+ */
 export declare function helmVar(name: string, value: string, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm block (named template block).
+ *
+ * @param name - Block name
+ * @param content - Block content
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'block'
+ *
+ * @example
+ * helmBlock('myapp.config', { key: 'value' })
+ */
 export declare function helmBlock(name: string, content: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a Helm comment block.
+ *
+ * @param text - Comment text
+ * @returns HelmConstruct of type 'comment'
+ *
+ * @example
+ * helmComment('This is a template comment')
+ * // Output: (curly-brace-slash-star) This is a template comment (star-slash-curly-brace)
+ */
 export declare function helmComment(text: string): HelmConstruct;
 export type HelmContent = string | number | boolean | null | undefined | HelmConstruct | HelmExpression | {
     [key: string]: HelmContent;
 } | HelmContent[];
+/**
+ * Options for whitespace control in Helm templates
+ */
 export interface HelmWhitespaceOptions {
+    /** Trim whitespace to the left of the construct ({{-) */
     trimLeft?: boolean;
+    /** Trim whitespace to the right of the construct (-}}) */
     trimRight?: boolean;
+    /** Render as inline (no newlines) */
     inline?: boolean;
 }
+/**
+ * Conditional rendering helper (if/else)
+ *
+ * @param condition - Helm template condition expression (e.g., '.Values.enabled')
+ * @param thenContent - Content to render if condition is true
+ * @param elseContent - Optional content to render if condition is false
+ * @param options - Whitespace control options
+ * @returns HelmConstruct representing the if/else block
+ *
+ * @example
+ * // Simple if
+ * helmIf('.Values.enabled', { replicas: 3 })
+ * // Output: {{- if .Values.enabled }}
+ * //         replicas: 3
+ * //         {{- end }}
+ *
+ * @example
+ * // If-else
+ * helmIf('.Values.production',
+ *   { replicas: 5 },
+ *   { replicas: 1 }
+ * )
+ * // Output: {{- if .Values.production }}
+ * //         replicas: 5
+ * //         {{- else }}
+ * //         replicas: 1
+ * //         {{- end }}
+ *
+ * @example
+ * // Nested with range
+ * helmIf('.Values.enabled', [
+ *   helmRange('$item', '.Values.items', {
+ *     name: '{{ $item.name }}',
+ *     value: '{{ $item.value }}'
+ *   })
+ * ])
+ *
+ * @since 2.14.0
+ */
 export declare function helmIf(condition: string, thenContent: HelmContent, elseContent?: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Creates a simple Helm if block without else (field-level conditional).
+ * This is specifically designed for conditionally including entire fields.
+ * When used as a field value, it wraps the field (key + value) in the conditional.
+ *
+ * @param condition - Helm template condition expression (e.g., '.Values.enabled')
+ * @param thenContent - Content to render if condition is true
+ * @param options - Whitespace control options
+ * @returns HelmConstruct representing the if block that wraps the field
+ *
+ * @example
+ * // Conditionally include replicas field
+ * {
+ *   spec: {
+ *     replicas: helmIfSimple('not .Values.autoscaling.enabled', helm('{{ .Values.replicaCount }}'))
+ *   }
+ * }
+ * // Output:
+ * // spec:
+ * //   {{- if not .Values.autoscaling.enabled }}
+ * //     replicas: {{ .Values.replicaCount }}
+ * //   {{- end }}
+ *
+ * @since 2.14.0
+ */
 export declare function helmIfSimple(condition: string, thenContent: HelmContent, options?: HelmWhitespaceOptions): HelmConstruct;
+/**
+ * Check if a value is a HelmConstruct
+ */
 export declare function isHelmConstruct(value: unknown): value is HelmConstruct;

package/dist/lib/utils/helmControlStructures.js

@@ -1,3 +1,14 @@
+/**
+ * @fileoverview Helm template control structure helpers
+ * Provides type-safe, composable helpers for Helm template constructs
+ * @since 2.14.0
+ */
+/**
+ * Creates a Helm fragment (composite of multiple contents).
+ * Useful for combining multiple constructs (e.g. multiple if blocks) into a single field value.
+ * @param contents List of Helm content to combine
+ * @returns HelmConstruct of type 'fragment'
+ */
 export function helmFragment(...contents) {
     return {
         __helmConstruct: true,
@@ -5,18 +16,43 @@ export function helmFragment(...contents) {
         data: contents,
     };
 }
+/**
+ * Creates a Helm expression marker.
+ * @param value Helm template expression string.
+ * @returns Helm expression marker object.
+ * @since 2.9.2
+ */
 export function createHelmExpression(value) {
     return {
         __helmExpression: true,
         value,
     };
 }
+/**
+ * Checks if a value is a Helm expression marker.
+ * @param value Value to check.
+ * @returns True if value is a Helm expression marker.
+ * @since 2.9.2
+ */
 export function isHelmExpression(value) {
     return (typeof value === 'object' &&
         value !== null &&
         '__helmExpression' in value &&
         value.__helmExpression === true);
 }
+/**
+ * Creates a Helm range (iteration) block.
+ *
+ * @param vars - Variable(s) to bind (e.g., 'item', '$key, $value', '$index, $item')
+ * @param collection - Helm expression for the collection to iterate (e.g., '.Values.items')
+ * @param content - Content to repeat for each iteration
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'range'
+ *
+ * helmRange('$key, $value', '.Values.secrets', {
+ *   [helmVar('$key')]: helmVar('$value')]
+ * })
+ */
 export function helmRange(vars, collection, content, options) {
     return {
         __helmConstruct: true,
@@ -29,6 +65,22 @@ export function helmRange(vars, collection, content, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm with block (scope/context switching).
+ *
+ * @param scope - Helm expression for the scope to switch to (e.g., '.Values.database')
+ * @param content - Content to execute with the new scope (where '.' refers to the scope)
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'with'
+ *
+ * @example
+ * // Simplify nested object access
+ * helmWith('.Values.database', {
+ *   host: helm('{{ .host }}'),
+ *   port: helm('{{ .port }}'),
+ *   username: helm('{{ .username }}')
+ * })
+ */
 export function helmWith(scope, content, options) {
     return {
         __helmConstruct: true,
@@ -40,6 +92,19 @@ export function helmWith(scope, content, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm include statement (template inclusion).
+ *
+ * @param templateName - Name of the template to include (e.g., 'myapp.labels')
+ * @param scope - Scope to pass to the template (usually '.')
+ * @param pipe - Optional pipe operations (e.g., 'nindent 4', 'quote')
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'include'
+ *
+ * @example
+ * helmInclude('myapp.labels', '.', { pipe: 'nindent 4' })
+ * // Output: {{ include "myapp.labels" . | nindent 4 }}
+ */
 export function helmInclude(templateName, scope = '.', options) {
     return {
         __helmConstruct: true,
@@ -52,6 +117,20 @@ export function helmInclude(templateName, scope = '.', options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm define block (template definition).
+ *
+ * @param name - Name of the template
+ * @param content - Template content
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'define'
+ *
+ * @example
+ * helmDefine('myapp.labels', {
+ *   'app.kubernetes.io/name': helm('{{ .Chart.Name }}'),
+ *   'app.kubernetes.io/instance': helm('{{ .Release.Name }}')
+ * })
+ */
 export function helmDefine(name, content, options) {
     return {
         __helmConstruct: true,
@@ -63,6 +142,18 @@ export function helmDefine(name, content, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm variable assignment.
+ *
+ * @param name - Variable name (with $ prefix)
+ * @param value - Value to assign
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'var'
+ *
+ * @example
+ * helmVar('$fullName', 'include "myapp.fullname" .')
+ * // Output: {{ $fullName := include "myapp.fullname" . }}
+ */
 export function helmVar(name, value, options) {
     return {
         __helmConstruct: true,
@@ -74,6 +165,17 @@ export function helmVar(name, value, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm block (named template block).
+ *
+ * @param name - Block name
+ * @param content - Block content
+ * @param options - Whitespace control options
+ * @returns HelmConstruct of type 'block'
+ *
+ * @example
+ * helmBlock('myapp.config', { key: 'value' })
+ */
 export function helmBlock(name, content, options) {
     return {
         __helmConstruct: true,
@@ -85,6 +187,16 @@ export function helmBlock(name, content, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a Helm comment block.
+ *
+ * @param text - Comment text
+ * @returns HelmConstruct of type 'comment'
+ *
+ * @example
+ * helmComment('This is a template comment')
+ * // Output: (curly-brace-slash-star) This is a template comment (star-slash-curly-brace)
+ */
 export function helmComment(text) {
     return {
         __helmConstruct: true,
@@ -92,6 +204,45 @@ export function helmComment(text) {
         data: { text },
     };
 }
+/**
+ * Conditional rendering helper (if/else)
+ *
+ * @param condition - Helm template condition expression (e.g., '.Values.enabled')
+ * @param thenContent - Content to render if condition is true
+ * @param elseContent - Optional content to render if condition is false
+ * @param options - Whitespace control options
+ * @returns HelmConstruct representing the if/else block
+ *
+ * @example
+ * // Simple if
+ * helmIf('.Values.enabled', { replicas: 3 })
+ * // Output: {{- if .Values.enabled }}
+ * //         replicas: 3
+ * //         {{- end }}
+ *
+ * @example
+ * // If-else
+ * helmIf('.Values.production',
+ *   { replicas: 5 },
+ *   { replicas: 1 }
+ * )
+ * // Output: {{- if .Values.production }}
+ * //         replicas: 5
+ * //         {{- else }}
+ * //         replicas: 1
+ * //         {{- end }}
+ *
+ * @example
+ * // Nested with range
+ * helmIf('.Values.enabled', [
+ *   helmRange('$item', '.Values.items', {
+ *     name: '{{ $item.name }}',
+ *     value: '{{ $item.value }}'
+ *   })
+ * ])
+ *
+ * @since 2.14.0
+ */
 export function helmIf(condition, thenContent, elseContent, options) {
     return {
         __helmConstruct: true,
@@ -104,6 +255,31 @@ export function helmIf(condition, thenContent, elseContent, options) {
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Creates a simple Helm if block without else (field-level conditional).
+ * This is specifically designed for conditionally including entire fields.
+ * When used as a field value, it wraps the field (key + value) in the conditional.
+ *
+ * @param condition - Helm template condition expression (e.g., '.Values.enabled')
+ * @param thenContent - Content to render if condition is true
+ * @param options - Whitespace control options
+ * @returns HelmConstruct representing the if block that wraps the field
+ *
+ * @example
+ * // Conditionally include replicas field
+ * {
+ *   spec: {
+ *     replicas: helmIfSimple('not .Values.autoscaling.enabled', helm('{{ .Values.replicaCount }}'))
+ *   }
+ * }
+ * // Output:
+ * // spec:
+ * //   {{- if not .Values.autoscaling.enabled }}
+ * //     replicas: {{ .Values.replicaCount }}
+ * //   {{- end }}
+ *
+ * @since 2.14.0
+ */
 export function helmIfSimple(condition, thenContent, options) {
     return {
         __helmConstruct: true,
@@ -111,11 +287,15 @@ export function helmIfSimple(condition, thenContent, options) {
         data: {
             condition,
             then: thenContent,
+            // Explicitly set else to undefined to mark this as a field-level conditional
             else: undefined,
         },
         ...(options ? { options } : {}),
     };
 }
+/**
+ * Check if a value is a HelmConstruct
+ */
 export function isHelmConstruct(value) {
     return (typeof value === 'object' &&
         value !== null &&

package/dist/lib/utils/helmHelpers/envHelpers.d.ts

@@ -1,2 +1,15 @@
+/**
+ * @fileoverview Environment and configuration management helpers for Helm templates
+ * @since 2.11.0
+ */
 import type { HelperDefinition } from './types.js';
+/**
+ * Environment and configuration management helpers
+ *
+ * These helpers provide robust environment variable handling, configuration merging,
+ * and environment-specific logic for Helm templates. They support common CI/CD patterns
+ * and configuration management best practices.
+ *
+ * @since 2.11.0
+ */
 export declare const ENV_HELPERS: HelperDefinition[];

package/dist/lib/utils/helmHelpers/envHelpers.js

@@ -1,3 +1,16 @@
+/**
+ * @fileoverview Environment and configuration management helpers for Helm templates
+ * @since 2.11.0
+ */
+/**
+ * Environment and configuration management helpers
+ *
+ * These helpers provide robust environment variable handling, configuration merging,
+ * and environment-specific logic for Helm templates. They support common CI/CD patterns
+ * and configuration management best practices.
+ *
+ * @since 2.11.0
+ */
 export const ENV_HELPERS = [
     {
         name: 'env.required',

package/dist/lib/utils/helmHelpers/gitopsHelpers.d.ts

@@ -1,2 +1,15 @@
+/**
+ * @fileoverview GitOps and CI/CD helpers for Helm templates
+ * @since 2.11.0
+ */
 import type { HelperDefinition } from './types.js';
+/**
+ * GitOps and CI/CD helpers
+ *
+ * These helpers provide integration with modern GitOps workflows and CI/CD systems.
+ * They support Git metadata, build information, image tagging strategies, and
+ * deployment annotations for traceability and auditability.
+ *
+ * @since 2.11.0
+ */
 export declare const GITOPS_HELPERS: HelperDefinition[];

package/dist/lib/utils/helmHelpers/gitopsHelpers.js

@@ -1,3 +1,16 @@
+/**
+ * @fileoverview GitOps and CI/CD helpers for Helm templates
+ * @since 2.11.0
+ */
+/**
+ * GitOps and CI/CD helpers
+ *
+ * These helpers provide integration with modern GitOps workflows and CI/CD systems.
+ * They support Git metadata, build information, image tagging strategies, and
+ * deployment annotations for traceability and auditability.
+ *
+ * @since 2.11.0
+ */
 export const GITOPS_HELPERS = [
     {
         name: 'git.commitSha',

package/dist/lib/utils/helmHelpers/index.d.ts

@@ -1,19 +1,93 @@
+/**
+ * @fileoverview Main index file for Helm helpers with organized exports and helper management functions
+ * @since 2.11.0
+ */
 export type { HelperDefinition, HelperCategory, CloudProvider, HelperOptions } from './types.js';
 export { ENV_HELPERS } from './envHelpers.js';
 export { GITOPS_HELPERS } from './gitopsHelpers.js';
 export { OBSERVABILITY_HELPERS } from './observabilityHelpers.js';
 export { VALIDATION_HELPERS } from './validationHelpers.js';
 import type { HelperDefinition, HelperCategory, HelperOptions } from './types.js';
+/**
+ * Performance-optimized helper lookup with O(1) time complexity
+ * @param category - Helper category to retrieve
+ * @returns Array of helper definitions for the specified category
+ * @throws {Error} If category is unknown
+ * @since 2.11.0
+ */
 export declare function getNewHelpersByCategory(category: HelperCategory): HelperDefinition[];
+/**
+ * Get all available new helper categories
+ * @returns Array of available helper categories
+ * @since 2.11.0
+ */
 export declare function getAvailableHelperCategories(): HelperCategory[];
+/**
+ * Get helpers for multiple categories
+ * @param categories - Array of categories to retrieve
+ * @returns Combined array of helper definitions
+ * @since 2.11.0
+ */
 export declare function getHelpersByCategories(categories: HelperCategory[]): HelperDefinition[];
+/**
+ * Get helpers based on options configuration
+ * @param options - Configuration options for helper inclusion
+ * @returns Array of helper definitions based on options
+ * @since 2.11.0
+ */
 export declare function getHelpersByOptions(options: HelperOptions): HelperDefinition[];
+/**
+ * Converts helper definitions to Helm template format
+ * @param helpers - Array of helper definitions
+ * @returns Formatted Helm template string
+ * @since 2.11.0
+ */
 export declare function formatNewHelpers(helpers: HelperDefinition[]): string;
+/**
+ * Generates complete _helpers.tpl content with new helpers
+ * @param options - Configuration options for helper inclusion
+ * @param customHelpers - Additional custom helpers
+ * @returns Complete helpers template content
+ * @since 2.11.0
+ */
 export declare function generateNewHelpersTemplate(options?: HelperOptions, customHelpers?: HelperDefinition[]): string;
+/**
+ * Cached helper compilation for better performance
+ * @param options - Configuration options for helper inclusion
+ * @param customHelpers - Additional custom helpers
+ * @returns Complete helpers template content from cache or newly generated
+ * @since 2.11.0
+ */
 export declare function getCachedNewHelpersTemplate(options?: HelperOptions, customHelpers?: HelperDefinition[]): string;
+/**
+ * Creates a custom helper definition
+ * @param name - Helper name
+ * @param template - Helper template content
+ * @returns Helper definition object
+ * @since 2.11.0
+ */
 export declare function createNewHelper(name: string, template: string): HelperDefinition;
+/**
+ * Validates helper names for Helm compatibility
+ * @param helpers - Array of helper definitions to validate
+ * @throws {Error} If any helper has an invalid name
+ * @since 2.11.0
+ */
 export declare function validateHelperNames(helpers: HelperDefinition[]): void;
+/**
+ * Filters helpers by name pattern
+ * @param helpers - Array of helper definitions to filter
+ * @param pattern - RegExp pattern to match against helper names
+ * @returns Filtered array of helper definitions
+ * @since 2.11.0
+ */
 export declare function filterHelpersByPattern(helpers: HelperDefinition[], pattern: RegExp): HelperDefinition[];
+/**
+ * Gets helper statistics for analysis
+ * @param helpers - Array of helper definitions to analyze
+ * @returns Statistics about the helpers
+ * @since 2.11.0
+ */
 export declare function getHelperStatistics(helpers: HelperDefinition[]): {
     totalHelpers: number;
     categoryCounts: Record<string, number>;