timonel 2.8.1 → 2.8.3

package/dist/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * @fileoverview Main entry point for Timonel - TypeScript library for programmatic Helm chart generation
- * @since 1.0.0
- */
 export * from './lib/helm.js';
 export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
@@ -11,4 +7,3 @@ export type { AWSALBIngressSpec, AWSEBSStorageClassSpec, AWSEFSStorageClassSpec,
 export type { KarpenterDisruption, KarpenterDisruptionBudget, KarpenterEC2NodeClassSpec, KarpenterNodeClaimSpec, KarpenterNodePoolSpec, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { AWS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, STANDARD_HELPERS, type HelperDefinition, } from './lib/utils/helmHelpers.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,13 +1,7 @@
-/**
- * @fileoverview Main entry point for Timonel - TypeScript library for programmatic Helm chart generation
- * @since 1.0.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';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
-// Re-export specific items from new modules to avoid conflicts
 export { AWS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, STANDARD_HELPERS, } from './lib/utils/helmHelpers.js';
-//# sourceMappingURL=index.js.map

package/dist/lib/helm.d.ts

@@ -1,159 +1,15 @@
-/**
- * @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
- */
-/**
- * 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 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 0.1.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 0.1.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 0.1.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 0.1.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 0.1.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 0.1.0
- */
 export declare function include(name: string, context?: string): string;
-/**
- * Branded types for better type safety in Helm template paths
- * @since 1.1.0
- */
 export type HelmPath = string & {
     readonly __brand: unique symbol;
 };
@@ -169,323 +25,23 @@ export type StringPath = HelmPath & {
 export type FloatPath = HelmPath & {
     readonly __floatType: unique symbol;
 };
-/**
- * Configuration options for typed reference creation
- * @since 1.1.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 1.1.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 0.1.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 0.1.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 0.1.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 0.1.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.6.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.7.4
- */
 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.6.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.6.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 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 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;
@@ -493,36 +49,8 @@ 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;
 }>, defaultContent?: string): string;
 export {};
-//# sourceMappingURL=helm.d.ts.map