@stacksjs/stx/dist/expressions.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Register a custom filter
 *
 * @param name - Filter name (used in templates as {{ value | filterName }})
 * @param fn - Filter function
 *
 * @example
 * ```typescript
 * // Register a custom filter
 * registerFilter('reverse', (value) => {
 *   return String(value).split('').reverse().join('')
 * })
 *
 * // Use in template: {{ name | reverse }}
 * ```
 */
export declare function registerFilter(name: string, fn: FilterFunction): void;
/**
 * Register multiple custom filters at once
 *
 * @param filters - Object mapping filter names to functions
 *
 * @example
 * ```typescript
 * registerFilters({
 *   reverse: (value) => String(value).split('').reverse().join(''),
 *   double: (value) => Number(value) * 2,
 * })
 * ```
 */
export declare function registerFilters(filters: Record<string, FilterFunction>): void;
/**
 * Get all available filters (built-in + custom)
 */
export declare function getAllFilters(): Record<string, FilterFunction>;
/**
 * Clear all custom filters (useful for testing)
 */
export declare function clearCustomFilters(): void;
/**
 * HTML escape function to prevent XSS
 */
export declare function escapeHtml(unsafe: string): string;
/**
 * Process template expressions including variables, filters, and operations
 */
export declare function processExpressions(template: string, context: Record<string, any>, filePath: string): string;
/**
 * Apply filters to a value
 */
export declare function applyFilters(value: any, filterExpression: string, context: Record<string, any>): any;
/**
 * Evaluate an expression within the given context
 * @param {string} expression - The expression to evaluate
 * @param {Record<string, any>} context - The context object containing variables
 * @param {boolean} silent - Whether to silently handle errors (return undefined) or throw
 * @returns The evaluated result
 */
export declare function evaluateExpression(expression: string, context: Record<string, any>, silent?: boolean): any;
/**
 * HTML unescape function to reverse escapeHtml
 */
export declare function unescapeHtml(html: string): string;
// =============================================================================
// Built-in Filters
// =============================================================================
export declare const defaultFilters: {
  // String transformation filters
  uppercase: (value: any, _context: Record<string, any>) => unknown;
  lowercase: (value: any, _context: Record<string, any>) => unknown;
  capitalize: (value: any, _context: Record<string, any>) => unknown;
  // Number filters
  number: (value: any, _context: Record<string, any>, decimals: number?) => unknown;
  // Array filters
  join: () => unknown;
  // Safety filters
  escape: (value: any, _context: Record<string, any>) => unknown;
  // Translation filter - uses context parameter instead of global state
  translate: (value: any, context: Record<string, any>, params: Record<string, any> = {}) => unknown;
  // Short alias for translate
  t: (value: any, context: Record<string, any>, params: Record<string, any> = {}) => unknown;
  // =========================================================================
  // Additional Utility Filters
  // =========================================================================

  // Truncate string to specified length with ellipsis
  truncate: (value: any, _context: Record<string, any>, length: number?, suffix: string?) => unknown;
  // Format date using Intl.DateTimeFormat
  date: (value: any, _context: Record<string, any>, format: string?, locale: string?) => unknown;
  // Format number as currency
  currency: (value: any, _context: Record<string, any>, currencyCode: string?, locale: string?) => unknown;
  // Pluralize word based on count
  pluralize: (value: any, _context: Record<string, any>, singular: string, plural?: string) => unknown;
  // Get first item from array or first character from string
  first: (value: any, _context: Record<string, any>) => unknown;
  // Get last item from array or last character from string
  last: (value: any, _context: Record<string, any>) => unknown;
  // Get length of array or string
  length: (value: any, _context: Record<string, any>) => unknown;
  // Convert to JSON string
  json: (value: any, _context: Record<string, any>, pretty: boolean?) => unknown;
  // Default value if null/undefined
  default: (value: any, _context: Record<string, any>, defaultValue: any?) => unknown;
  // Reverse string or array
  reverse: (value: any, _context: Record<string, any>) => unknown;
  // Slice array or string
  slice: (value: any, _context: Record<string, any>, start: number?, end?: number) => unknown;
  // Replace text
  replace: (value: any, _context: Record<string, any>, search: string, replacement: string?) => unknown;
  // Strip HTML tags
  stripTags: (value: any, _context: Record<string, any>) => unknown;
  // URL encode
  urlencode: (value: any, _context: Record<string, any>) => unknown;
  // Absolute value
  abs: (value: any, _context: Record<string, any>) => unknown;
  // Round number
  round: (value: any, _context: Record<string, any>, decimals: number?) => unknown
};
/**
 * Add basic filter support to expressions
 * Filter functions receive the value to transform, optional args, and the context object
 */
export type FilterFunction = (value: any, context: Record<string, any>, ...args: any[]) => any