timonel 3.1.1 → 3.1.2

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Main entry point for Timonel - TypeScript library for programmatic Helm chart generation
+ * @since 2.8.0+
+ */
 export * from './lib/helm.js';
 export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
@@ -18,4 +22,4 @@ export { UmbrellaRutter } from './lib/umbrellaRutter.js';
 export { helmIf, helmIfSimple, 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 { loadEnvVarsConfig, generateEnvVars, loadAndGenerateEnvVars, type EnvVarConfig, type LoadEnvVarsOptions, } from './lib/utils/envVarsLoader.js';
 export { dumpHelmAwareYaml, validateHelmYaml, type HelmValidationError, type HelmValidationResult, } from './lib/utils/helmYamlSerializer.js';
-export { valuesRef, isHelmValue, isHelmCondition, isHelmFieldConditional, isHelmRange, isHelmWith, serializeHelmValue, serializeHelmCondition, type HelmValue, type HelmCondition, type HelmFieldConditional, type HelmRange, type HelmWith, type HelmHelpers, } from './lib/utils/valuesRef.js';
+export { valuesRef, isHelmValue, isHelmCondition, isHelmFieldConditional, isHelmRange, isHelmWith, serializeHelmValue, serializeHelmCondition, type HelmValue, type HelmValueRef, type ValuesRef, type HelmCondition, type HelmFieldConditional, type HelmRange, type HelmWith, type HelmHelpers, } from './lib/utils/valuesRef.js';

package/dist/index.js

@@ -1,17 +1,29 @@
+/**
+ * @fileoverview Main entry point for Timonel - TypeScript library for programmatic Helm chart generation
+ * @since 2.8.0+
+ */
 export * from './lib/helm.js';
 export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
 export * from './lib/security.js';
 export * from './lib/umbrella.js';
+// Policy Engine
 export * from './lib/policy/index.js';
+// Input Validation
 export * from './lib/validation/inputValidator.js';
+// Templates
 export { FlexibleSubchart, createFlexibleSubchart } from './lib/templates/flexible-subchart.js';
 export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella-chart.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
+// Helm Helpers
 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';
+// Logging Utilities
 export { createLogger, logger, LogLevel, TimonelLogger, } from './lib/utils/logger.js';
 export { UmbrellaRutter } from './lib/umbrellaRutter.js';
 export { helmIf, helmIfSimple, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, } from './lib/utils/helmControlStructures.js';
+// Environment Variables Loader
 export { loadEnvVarsConfig, generateEnvVars, loadAndGenerateEnvVars, } from './lib/utils/envVarsLoader.js';
+// Helm YAML Serialization Utilities
 export { dumpHelmAwareYaml, validateHelmYaml, } from './lib/utils/helmYamlSerializer.js';
+// Type-safe Values Reference
 export { valuesRef, isHelmValue, isHelmCondition, isHelmFieldConditional, isHelmRange, isHelmWith, serializeHelmValue, serializeHelmCondition, } from './lib/utils/valuesRef.js';

package/dist/lib/helm.d.ts

@@ -1,15 +1,159 @@
+/**
+ * @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 2.8.0+++
+ */
+/**
+ * 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 2.8.0+
+ */
 export declare function valuesRef(path: string): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function requiredValuesRef(path: string, message?: string): string;
+/**
+ * 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 2.8.0+
+ *
+ * @example
+ * ```typescript
+ * const deploymentName = `${helm.releaseName}-deployment`;
+ * // Uses: '{{ .Release.Name }}-deployment'
+ *
+ * const version = helm.chartVersion;
+ * // Uses: '{{ .Chart.Version }}'
+ * ```
+ */
 export declare const helm: {
+    /** Release name: {{ .Release.Name }} */
     releaseName: string;
+    /** Chart name: {{ .Chart.Name }} */
     chartName: string;
+    /** Chart version: {{ .Chart.Version }} */
     chartVersion: string;
+    /** Release namespace: {{ .Release.Namespace }} */
     namespace: string;
 };
+/**
+ * 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 2.8.0+
+ */
 export declare function quote(expr: string): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function indent(n: number, expr: string): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function template(name: string, context?: string): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function include(name: string, context?: string): string;
+/**
+ * Branded types for better type safety in Helm template paths
+ * @since 2.8.0+
+ */
 export type HelmPath = string & {
     readonly __brand: unique symbol;
 };
@@ -25,23 +169,323 @@ export type StringPath = HelmPath & {
 export type FloatPath = HelmPath & {
     readonly __floatType: unique symbol;
 };
+/**
+ * Configuration options for typed reference creation
+ * @since 2.8.0+
+ */
 interface TypedRefOptions {
+    /** Whether to include default value handling */
     withDefault?: boolean;
+    /** Default value to use if the path is not set */
     defaultValue?: string | number | boolean;
+    /** Whether to quote string values */
     quote?: boolean;
 }
+/**
+ * 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 2.8.0+
+ */
 export declare function createTypedRef(path: string, type: 'number' | 'boolean' | 'string' | 'float', options?: TypedRefOptions): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function numberRef(path: string, options?: TypedRefOptions): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function boolRef(path: string, options?: TypedRefOptions): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function stringRef(path: string, options?: TypedRefOptions): string;
+/**
+ * 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 2.8.0+
+ */
 export declare function floatRef(path: string, options?: TypedRefOptions): string;
+/**
+ * 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.8.0+
+ */
 export declare function conditionalRef(path: string, condition: string): string;
+/**
+ * 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.8.0+
+ */
 export declare function conditionalManifest(yamlContent: string, condition: string): string;
+/**
+ * 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.8.0+
+ */
 export declare function defaultRef(path: string, defaultValue: string): string;
+/**
+ * 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.8.0+
+ */
 export declare function base64Ref(path: string): string;
+/**
+ * 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 declare function jsonRef(path: string): string;
+/**
+ * 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 2.8.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 declare function helmIf(condition: string, content: string, elseContent?: string): string;
+/**
+ * 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 declare function helmWith(path: string, content: string, elseContent?: string): string;
+/**
+ * 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 declare function helmRange(collection: string, content: string, options?: {
     keyValue?: boolean;
     keyVar?: string;
@@ -49,6 +493,33 @@ export declare function helmRange(collection: string, content: string, options?:
     indexVar?: string;
     itemVar?: string;
 }): string;
+/**
+ * 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 declare function helmIfElseIf(branches: Array<{
     condition: string;
     content: string;