Template Rendering with Dual Context Layers

Build a template rendering system that supports dual context layers for dynamic URL generation in a business intelligence tool. The system must handle both current cell values and references to other fields in the same data row.

Capabilities

Template Rendering

Implement a function that renders templates with dual context access:

• Current cell value context with raw and formatted representations
• Row context providing access to all fields from all tables in the current row
• Template syntax using ${} delimiters
• Support for Liquid template filters (e.g., url_encode)

Static Dependency Analysis

Implement a function that extracts row field dependencies from templates without executing them:

• Parse template AST to identify field references
• Return list of dependent fields in format tableName_fieldName
• Validate reference format (must be row.{table}.{field}.(raw|formatted))
• Reject invalid references with descriptive error messages

Value Reference Support

Support references to the current cell value:

• ${value.raw} - access raw database value
• ${value.formatted} - access pre-formatted display string

Row Reference Support

Support references to other fields in the same row:

• Pattern: ${row.{table}.{field}.(raw|formatted)}
• Nested object navigation for multi-table row data
• Access both raw and formatted values for any field

Test Cases

• Renders a template with only value references: ${value.raw} returns the raw value from the current cell @test

• Renders a template with row references: ${row.customers.customer_id.raw} accesses the customer_id field from the customers table @test

• Applies Liquid filters correctly: ${value.raw | url_encode} applies URL encoding to the raw value @test

• Extracts dependencies from row references: template with ${row.customers.customer_id.raw} returns ['customers_customer_id'] @test

• Rejects invalid row references: template with ${row.customer_id.raw} (missing table name) throws an error @test

• Renders complex templates with multiple references: combines value and multiple row references in a single URL @test

• Returns empty dependencies for value-only templates: template with only ${value.raw} returns empty array @test

Implementation

@generates

API

/**
 * ResultValue represents a data cell with both raw database value and formatted display string
 */
type ResultValue = {
    raw: unknown;
    formatted: string;
};

/**
 * Renders a template string with dual context layers
 *
 * @param template - Template string using ${} delimiters
 * @param value - Current cell value with raw and formatted representations
 * @param row - Complete row data organized as row[tableName][fieldName] = ResultValue
 * @returns Rendered string with all template variables resolved
 */
export function renderTemplatedUrl(
    template: string,
    value: ResultValue,
    row: Record<string, Record<string, ResultValue>>
): string;

/**
 * Extracts row field dependencies from a template without executing it
 * Uses AST parsing to identify all row.{table}.{field} references
 *
 * @param template - Template string to analyze
 * @returns Array of field identifiers in format 'tableName_fieldName'
 * @throws Error if template contains invalid row references
 */
export function getTemplatedUrlRowDependencies(
    template: string
): string[];

Dependencies { .dependencies }

@lightdash/common { .dependency }

Provides template rendering utilities and type definitions for business intelligence operations.