timonel 2.8.0-beta.5 → 2.8.1

package/dist/{src/lib → lib}/helm.d.ts

@@ -150,6 +150,47 @@ export declare function template(name: string, context?: string): string;
  * @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;
+};
+export type NumberPath = HelmPath & {
+    readonly __numberType: unique symbol;
+};
+export type BooleanPath = HelmPath & {
+    readonly __booleanType: unique symbol;
+};
+export type StringPath = HelmPath & {
+    readonly __stringType: unique symbol;
+};
+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
  *
@@ -157,6 +198,7 @@ export declare function include(name: string, context?: string): string;
  * 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
  *
@@ -168,11 +210,12 @@ export declare function include(name: string, context?: string): string;
  *
  * @since 0.1.0
  */
-export declare function numberRef(path: string): string;
+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
  *
@@ -184,11 +227,12 @@ export declare function numberRef(path: string): string;
  *
  * @since 0.1.0
  */
-export declare function boolRef(path: string): string;
+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
  *
@@ -200,11 +244,12 @@ export declare function boolRef(path: string): string;
  *
  * @since 0.1.0
  */
-export declare function stringRef(path: string): string;
+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
  *
@@ -216,7 +261,7 @@ export declare function stringRef(path: string): string;
  *
  * @since 0.1.0
  */
-export declare function floatRef(path: string): string;
+export declare function floatRef(path: string, options?: TypedRefOptions): string;
 /**
  * Creates a conditional reference to a value in .Values
  *
@@ -237,6 +282,32 @@ export declare function floatRef(path: string): string;
  * @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
  *
@@ -295,4 +366,163 @@ export declare function base64Ref(path: string): string;
  * @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;
+    valueVar?: string;
+    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

package/dist/lib/helm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helm.d.ts","sourceRoot":"","sources":["../../src/lib/helm.ts"],"names":[],"mappings":"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"}