timonel 3.1.1 → 3.1.2

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

@@ -1,102 +1,233 @@
+/**
+ * Type-safe Helm values reference system.
+ *
+ * ValuesRef exposes the shape of the caller-provided values interface while
+ * preserving a runtime proxy that renders Helm expressions.
+ */
 import { type HelmExpression } from './helmControlStructures.js';
 declare const HELM_VALUE_SYMBOL: unique symbol;
+type HelmScalar = string | number | boolean;
+type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+type StringKeyOf<T> = Extract<keyof T, string>;
+type RuntimeReservedValueKey = 'toJSON' | 'toString' | 'valueOf';
+type HelmValueReservedKey = Extract<keyof HelmValue<unknown>, string> | RuntimeReservedValueKey;
+/**
+ * A Helm value reference with mapped properties that mirror the supplied
+ * TypeScript value shape. Keys reserved by the ValuesRef API remain accessible
+ * through the typed `at()` accessor.
+ */
+export type HelmValueRef<T> = HelmValue<T> & (T extends readonly unknown[] ? object : T extends object ? {
+    readonly [K in Exclude<StringKeyOf<T>, HelmValueReservedKey>]-?: HelmValueRef<T[K]>;
+} : object);
+/**
+ * Reference to a Helm value or scoped Helm expression.
+ *
+ * Instances are runtime proxies. The generic type preserves the shape of the referenced value
+ * while helper methods compose Helm/Sprig expressions.
+ */
 export interface HelmValue<T = unknown> {
+    /** Internal runtime marker used by Timonel serializers. */
     [HELM_VALUE_SYMBOL]: true;
+    /** Internal Helm expression path represented by this proxy. */
     __path: string;
+    /** Type-only marker; it is not populated at runtime. */
     __type?: T;
-    eq(value: HelmValue | string | number | boolean): HelmCondition;
-    ne(value: HelmValue | string | number | boolean): HelmCondition;
-    gt(value: HelmValue | number): HelmCondition;
-    ge(value: HelmValue | number): HelmCondition;
-    lt(value: HelmValue | number): HelmCondition;
-    le(value: HelmValue | number): HelmCondition;
+    /**
+     * Access a typed property whose name collides with a ValuesRef method or root helper.
+     * @param key - Property key from the current TypeScript values type
+     * @returns A typed proxy for the nested value
+     */
+    at<K extends StringKeyOf<T>>(key: K): HelmValueRef<T[K]>;
+    /** Compare the value for equality. */
+    eq(value: HelmValueRef<unknown> | HelmScalar): HelmCondition;
+    /** Compare the value for inequality. */
+    ne(value: HelmValueRef<unknown> | HelmScalar): HelmCondition;
+    /** Compare whether the value is greater than another numeric value/reference. */
+    gt(value: HelmValueRef<unknown> | number): HelmCondition;
+    /** Compare whether the value is greater than or equal to another numeric value/reference. */
+    ge(value: HelmValueRef<unknown> | number): HelmCondition;
+    /** Compare whether the value is less than another numeric value/reference. */
+    lt(value: HelmValueRef<unknown> | number): HelmCondition;
+    /** Compare whether the value is less than or equal to another numeric value/reference. */
+    le(value: HelmValueRef<unknown> | number): HelmCondition;
+    /** Negate the truthiness of the referenced Helm value. */
     not(): HelmCondition;
+    /** Combine the referenced value with another condition using Helm `and`. */
     and(other: HelmCondition): HelmCondition;
+    /** Combine the referenced value with another condition using Helm `or`. */
     or(other: HelmCondition): HelmCondition;
-    default(defaultValue: HelmValue | string | number | boolean): HelmValue<T>;
-    quote(): HelmValue<string>;
-    upper(): HelmValue<string>;
-    lower(): HelmValue<string>;
-    title(): HelmValue<string>;
-    trim(): HelmValue<string>;
-    trimPrefix(prefix: string): HelmValue<string>;
-    trimSuffix(suffix: string): HelmValue<string>;
-    replace(old: string, newStr: string): HelmValue<string>;
+    /** Apply Helm `default` while preserving the referenced value type. */
+    default(defaultValue: HelmValueRef<unknown> | HelmScalar): HelmValueRef<T>;
+    /** Pipe the value through `quote`. */
+    quote(): HelmValueRef<string>;
+    /** Pipe the value through `upper`. */
+    upper(): HelmValueRef<string>;
+    /** Pipe the value through `lower`. */
+    lower(): HelmValueRef<string>;
+    /** Pipe the value through `title`. */
+    title(): HelmValueRef<string>;
+    /** Pipe the value through `trim`. */
+    trim(): HelmValueRef<string>;
+    /** Remove a prefix with Sprig `trimPrefix`. */
+    trimPrefix(prefix: string): HelmValueRef<string>;
+    /** Remove a suffix with Sprig `trimSuffix`. */
+    trimSuffix(suffix: string): HelmValueRef<string>;
+    /** Replace string occurrences with Sprig `replace`. */
+    replace(old: string, newStr: string): HelmValueRef<string>;
+    /** Test whether the referenced string contains a substring. */
     contains(substr: string): HelmCondition;
+    /** Test whether the referenced string starts with a prefix. */
     hasPrefix(prefix: string): HelmCondition;
+    /** Test whether the referenced string ends with a suffix. */
     hasSuffix(suffix: string): HelmCondition;
-    trunc(length: number): HelmValue<string>;
+    /** Truncate the referenced string to the requested length. */
+    trunc(length: number): HelmValueRef<string>;
+    /** Test the Helm runtime kind of the referenced value. */
     kindIs(kind: 'string' | 'slice' | 'map' | 'bool' | 'int' | 'float'): HelmCondition;
+    /** Test whether the referenced map contains a key. */
     hasKey(key: string): HelmCondition;
-    toYaml(): HelmValue<string>;
-    toJson(): HelmValue<string>;
-    nindent(spaces: number): HelmValue<string>;
-    indent(spaces: number): HelmValue<string>;
+    /** Serialize the referenced value with Helm `toYaml`. */
+    toYaml(): HelmValueRef<string>;
+    /** Serialize the referenced value with Helm `toJson`. */
+    toJson(): HelmValueRef<string>;
+    /** Apply Helm/Sprig `nindent`. */
+    nindent(spaces: number): HelmValueRef<string>;
+    /** Apply Helm/Sprig `indent`. */
+    indent(spaces: number): HelmValueRef<string>;
+    /** Convert the proxy to Timonel's lower-level HelmExpression marker. */
     toExpression(): HelmExpression;
-    if<V>(condition: HelmCondition, thenValue: V): HelmFieldConditional<V>;
-    ifElse<V>(condition: HelmCondition, thenValue: V, elseValue: V): HelmValue<V>;
-    range<V>(callback: (item: HelmValue<T extends (infer U)[] ? U : unknown>, index: HelmValue<number>) => V): HelmRange<V>;
-    with<V>(callback: (ctx: HelmValue<T>) => V): HelmWith<V>;
+    /**
+     * Conditionally include a field value during Helm rendering.
+     * @param condition - Helm condition or value whose truthiness controls inclusion
+     * @param thenValue - Value emitted when the condition succeeds
+     */
+    if<V>(condition: HelmCondition | HelmValueRef<unknown>, thenValue: V): HelmFieldConditional<V>;
+    /**
+     * Build a Helm ternary expression.
+     * @param condition - Condition selecting between the two values
+     * @param thenValue - Value returned when the condition is true
+     * @param elseValue - Value returned when the condition is false
+     */
+    ifElse<V extends HelmValueRef<unknown> | HelmScalar>(condition: HelmCondition, thenValue: V, elseValue: V): HelmValueRef<V extends HelmValueRef<infer U> ? U : V>;
+    /**
+     * Create a typed Helm `range` block over an array value.
+     * @param callback - Callback receiving typed item and index proxies
+     */
+    range<V>(callback: (item: HelmValueRef<ArrayElement<T>>, index: HelmValueRef<number>) => V): HelmRange<V, ArrayElement<T>>;
+    /**
+     * Create a Helm `with` block scoped to the referenced value.
+     * @param callback - Callback receiving a proxy rooted at Helm `.` within the block
+     */
+    with<V>(callback: (ctx: HelmValueRef<T>) => V): HelmWith<V, T>;
 }
+/** Represents a composable Helm boolean condition. */
 export interface HelmCondition {
+    /** Internal runtime marker used by Timonel serializers. */
     [HELM_VALUE_SYMBOL]: true;
+    /** Raw Helm condition body without template delimiters. */
     __condition: string;
+    /** Negate this condition. */
     not(): HelmCondition;
+    /** Combine this condition with another using Helm `and`. */
     and(other: HelmCondition): HelmCondition;
+    /** Combine this condition with another using Helm `or`. */
     or(other: HelmCondition): HelmCondition;
+    /** Return the raw Helm condition body. */
     toString(): string;
 }
+/** Represents a field-level conditional consumed by the Helm YAML serializer. */
 export interface HelmFieldConditional<T> {
+    /** Runtime marker for serializer detection. */
     __helmFieldConditional: true;
+    /** Condition controlling whether the field is emitted. */
     condition: HelmCondition;
+    /** Field value emitted when the condition succeeds. */
     thenValue: T;
+    /** Optional compatibility else value. */
     elseValue?: T;
 }
-export interface HelmRange<T> {
+/** Represents a typed Helm `range` block. */
+export interface HelmRange<T, TItem = unknown> {
+    /** Runtime marker for serializer detection. */
     __helmRange: true;
-    source: HelmValue;
-    callback: (item: HelmValue, index: HelmValue<number>) => T;
+    /** Array value being iterated. */
+    source: HelmValueRef<readonly TItem[]>;
+    /** Callback used by the serializer with scoped item/index proxies. */
+    callback: (item: HelmValueRef<TItem>, index: HelmValueRef<number>) => T;
 }
-export interface HelmWith<T> {
+/** Represents a typed Helm `with` block. */
+export interface HelmWith<T, TContext = unknown> {
+    /** Runtime marker for serializer detection. */
     __helmWith: true;
-    source: HelmValue;
-    callback: (ctx: HelmValue) => T;
+    /** Value that becomes the Helm `.` scope. */
+    source: HelmValueRef<TContext>;
+    /** Callback used by the serializer with a scoped context proxy. */
+    callback: (ctx: HelmValueRef<TContext>) => T;
 }
+/** Helper context for Helm built-ins exposed on the root `ValuesRef`. */
 export interface HelmHelpers {
-    include(templateName: string, context?: '.' | HelmValue): HelmValue<string>;
-    printf(format: string, ...args: (HelmValue | string | number)[]): HelmValue<string>;
+    /** Render Helm `include` for a named template and context. */
+    include(templateName: string, context?: '.' | HelmValueRef<unknown>): HelmValueRef<string>;
+    /** Render Helm `printf` with typed value references or scalar arguments. */
+    printf(format: string, ...args: Array<HelmValueRef<unknown> | string | number>): HelmValueRef<string>;
+    /** References to Helm `.Release` built-ins. */
     release: {
-        name: HelmValue<string>;
-        namespace: HelmValue<string>;
-        service: HelmValue<string>;
-        isUpgrade: HelmValue<boolean>;
-        isInstall: HelmValue<boolean>;
-        revision: HelmValue<number>;
+        name: HelmValueRef<string>;
+        namespace: HelmValueRef<string>;
+        service: HelmValueRef<string>;
+        isUpgrade: HelmValueRef<boolean>;
+        isInstall: HelmValueRef<boolean>;
+        revision: HelmValueRef<number>;
     };
+    /** References to Helm `.Chart` built-ins. */
     chart: {
-        name: HelmValue<string>;
-        version: HelmValue<string>;
-        appVersion: HelmValue<string>;
-        type: HelmValue<string>;
+        name: HelmValueRef<string>;
+        version: HelmValueRef<string>;
+        appVersion: HelmValueRef<string>;
+        type: HelmValueRef<string>;
     };
+    /** References to selected Helm `.Capabilities` built-ins. */
     capabilities: {
         kubeVersion: {
-            version: HelmValue<string>;
-            major: HelmValue<string>;
-            minor: HelmValue<string>;
+            version: HelmValueRef<string>;
+            major: HelmValueRef<string>;
+            minor: HelmValueRef<string>;
         };
         apiVersions: {
+            /** Test whether the target cluster advertises a Kubernetes API version. */
             has(apiVersion: string): HelmCondition;
         };
     };
+    /** Escape hatch for conditions that cannot be expressed through typed helpers. */
     rawCondition(condition: string): HelmCondition;
 }
-export declare function valuesRef<T extends Record<string, unknown>>(): HelmValue<T> & HelmHelpers;
-export declare function isHelmValue(value: unknown): value is HelmValue;
+/**
+ * Creates the runtime proxy used by ValuesRef and by serializer callback scopes.
+ * This function is intentionally not re-exported from the package root.
+ */
+export declare function createHelmValueProxy<T>(path: string): HelmValueRef<T>;
+type HelmHelperKey = Extract<keyof HelmHelpers, string>;
+/**
+ * Root ValuesRef shape. Root Helm helper names are reserved and can be reached
+ * as values through `at()`, for example `v.at('release')`.
+ */
+export type ValuesRef<T extends object> = HelmValue<T> & HelmHelpers & (T extends readonly unknown[] ? object : {
+    readonly [K in Exclude<StringKeyOf<T>, HelmValueReservedKey | HelmHelperKey>]-?: HelmValueRef<T[K]>;
+});
+/** Creates a type-safe reference tree rooted at `.Values`. */
+export declare function valuesRef<T extends object>(): ValuesRef<T>;
+/** Check if a value is a Helm value proxy. */
+export declare function isHelmValue(value: unknown): value is HelmValueRef<unknown>;
+/** Check if a value is a Helm condition. */
 export declare function isHelmCondition(value: unknown): value is HelmCondition;
+/** Check if a value is a field-level conditional. */
 export declare function isHelmFieldConditional(value: unknown): value is HelmFieldConditional<unknown>;
-export declare function isHelmRange(value: unknown): value is HelmRange<unknown>;
-export declare function isHelmWith(value: unknown): value is HelmWith<unknown>;
-export declare function serializeHelmValue(value: HelmValue): string;
+/** Check if a value is a range block. */
+export declare function isHelmRange(value: unknown): value is HelmRange<unknown, unknown>;
+/** Check if a value is a with block. */
+export declare function isHelmWith(value: unknown): value is HelmWith<unknown, unknown>;
+/** Serialize a Helm value reference to template syntax. */
+export declare function serializeHelmValue(value: HelmValueRef<unknown>): string;
+/** Serialize a Helm condition body. */
 export declare function serializeHelmCondition(condition: HelmCondition): string;
 export {};