@marktoflow/core 2.0.0-alpha.14 → 2.0.0-alpha.15

package/dist/expression-helpers.js

@@ -0,0 +1,697 @@
+/**
+ * Expression Helper Library for marktoflow
+ *
+ * Provides pipeline-style filters for template expressions:
+ * {{ value | filter1 | filter2(arg) | filter3 }}
+ *
+ * Categories:
+ * - String helpers: split, join, trim, upper, lower, slugify, prefix, suffix
+ * - Array helpers: first, last, nth, map, filter, unique, count, sum
+ * - Object helpers: path, keys, values, merge, pick, omit
+ * - Date helpers: now, format_date, add_days, subtract_days
+ * - Logic helpers: default, or, and, not
+ * - Validation helpers: is_array, is_object, is_empty, is_null
+ */
+// ============================================================================
+// String Helpers
+// ============================================================================
+/**
+ * Split string by delimiter
+ * Usage: {{ "a,b,c" | split(',') }} → ['a', 'b', 'c']
+ */
+export function split(value, delimiter = ',') {
+    const str = String(value);
+    return str.split(delimiter);
+}
+/**
+ * Join array elements
+ * Usage: {{ ['a', 'b', 'c'] | join(', ') }} → "a, b, c"
+ */
+export function join(value, separator = ',') {
+    if (!Array.isArray(value)) {
+        return String(value);
+    }
+    return value.join(separator);
+}
+/**
+ * Trim whitespace
+ * Usage: {{ "  hello  " | trim }} → "hello"
+ */
+export function trim(value) {
+    return String(value).trim();
+}
+/**
+ * Convert to uppercase
+ * Usage: {{ "hello" | upper }} → "HELLO"
+ */
+export function upper(value) {
+    return String(value).toUpperCase();
+}
+/**
+ * Convert to lowercase
+ * Usage: {{ "HELLO" | lower }} → "hello"
+ */
+export function lower(value) {
+    return String(value).toLowerCase();
+}
+/**
+ * Convert to title case
+ * Usage: {{ "hello world" | title }} → "Hello World"
+ */
+export function title(value) {
+    const str = String(value);
+    return str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.slice(1).toLowerCase());
+}
+/**
+ * Capitalize first letter
+ * Usage: {{ "hello" | capitalize }} → "Hello"
+ */
+export function capitalize(value) {
+    const str = String(value);
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+ * Convert to URL-friendly slug
+ * Usage: {{ "Hello World!" | slugify }} → "hello-world"
+ */
+export function slugify(value) {
+    return String(value)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Add prefix to string
+ * Usage: {{ "hello" | prefix('@') }} → "@hello"
+ */
+export function prefix(value, prefixStr) {
+    return prefixStr + String(value);
+}
+/**
+ * Add suffix to string
+ * Usage: {{ "hello" | suffix('!') }} → "hello!"
+ */
+export function suffix(value, suffixStr) {
+    return String(value) + suffixStr;
+}
+/**
+ * Replace all occurrences
+ * Usage: {{ "hello world" | replace('world', 'there') }} → "hello there"
+ */
+export function replace(value, search, replaceWith) {
+    return String(value).replace(new RegExp(search, 'g'), replaceWith);
+}
+/**
+ * Truncate string to length
+ * Usage: {{ "hello world" | truncate(5) }} → "hello..."
+ */
+export function truncate(value, length, ellipsis = '...') {
+    const str = String(value);
+    if (str.length <= length)
+        return str;
+    return str.slice(0, length) + ellipsis;
+}
+/**
+ * Extract substring
+ * Usage: {{ "hello world" | substring(0, 5) }} → "hello"
+ */
+export function substring(value, start, end) {
+    return String(value).substring(start, end);
+}
+/**
+ * Check if string/array contains value
+ * Usage: {{ "hello world" | contains('world') }} → true
+ */
+export function contains(value, search) {
+    if (typeof value === 'string') {
+        return value.includes(String(search));
+    }
+    if (Array.isArray(value)) {
+        return value.includes(search);
+    }
+    return false;
+}
+// ============================================================================
+// Array Helpers
+// ============================================================================
+/**
+ * Get first element
+ * Usage: {{ [1, 2, 3] | first }} → 1
+ */
+export function first(value) {
+    if (Array.isArray(value)) {
+        return value[0];
+    }
+    return value;
+}
+/**
+ * Get last element
+ * Usage: {{ [1, 2, 3] | last }} → 3
+ */
+export function last(value) {
+    if (Array.isArray(value)) {
+        return value[value.length - 1];
+    }
+    return value;
+}
+/**
+ * Get nth element (0-indexed)
+ * Usage: {{ [1, 2, 3] | nth(1) }} → 2
+ */
+export function nth(value, index) {
+    if (Array.isArray(value)) {
+        return value[index];
+    }
+    return value;
+}
+/**
+ * Get array length or object property count
+ * Usage: {{ [1, 2, 3] | count }} → 3
+ */
+export function count(value) {
+    if (Array.isArray(value)) {
+        return value.length;
+    }
+    if (typeof value === 'string') {
+        return value.length;
+    }
+    if (typeof value === 'object' && value !== null) {
+        // Check for common count properties
+        const obj = value;
+        if ('length' in obj && typeof obj.length === 'number')
+            return obj.length;
+        if ('total' in obj && typeof obj.total === 'number')
+            return obj.total;
+        if ('count' in obj && typeof obj.count === 'number')
+            return obj.count;
+        return Object.keys(value).length;
+    }
+    return 0;
+}
+/**
+ * Sum array of numbers
+ * Usage: {{ [1, 2, 3] | sum }} → 6
+ */
+export function sum(value) {
+    if (!Array.isArray(value))
+        return 0;
+    return value.reduce((acc, val) => acc + Number(val), 0);
+}
+/**
+ * Get unique values
+ * Usage: {{ [1, 2, 2, 3] | unique }} → [1, 2, 3]
+ */
+export function unique(value) {
+    if (!Array.isArray(value))
+        return [value];
+    return Array.from(new Set(value));
+}
+/**
+ * Flatten array one level
+ * Usage: {{ [[1, 2], [3, 4]] | flatten }} → [1, 2, 3, 4]
+ */
+export function flatten(value) {
+    if (!Array.isArray(value))
+        return [value];
+    return value.flat(1);
+}
+/**
+ * Reverse array
+ * Usage: {{ [1, 2, 3] | reverse }} → [3, 2, 1]
+ */
+export function reverse(value) {
+    if (!Array.isArray(value))
+        return [value];
+    return [...value].reverse();
+}
+/**
+ * Sort array
+ * Usage: {{ [3, 1, 2] | sort }} → [1, 2, 3]
+ * Usage: {{ [3, 1, 2] | sort(true) }} → [3, 2, 1]
+ */
+export function sort(value, reverse = false) {
+    if (!Array.isArray(value))
+        return [value];
+    const sorted = [...value].sort((a, b) => {
+        if (typeof a === 'number' && typeof b === 'number')
+            return a - b;
+        return String(a).localeCompare(String(b));
+    });
+    return reverse ? sorted.reverse() : sorted;
+}
+/**
+ * Get array slice
+ * Usage: {{ [1, 2, 3, 4, 5] | slice(1, 3) }} → [2, 3]
+ */
+export function slice(value, start, end) {
+    if (!Array.isArray(value))
+        return [value];
+    return value.slice(start, end);
+}
+// ============================================================================
+// Object Helpers
+// ============================================================================
+/**
+ * Get value at path
+ * Usage: {{ obj | path('user.name') }} → obj.user.name
+ */
+export function path(value, pathStr) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const keys = pathStr.split('.');
+    let result = value;
+    for (const key of keys) {
+        if (typeof result !== 'object' || result === null) {
+            return undefined;
+        }
+        result = result[key];
+    }
+    return result;
+}
+/**
+ * Get object keys
+ * Usage: {{ {a: 1, b: 2} | keys }} → ['a', 'b']
+ */
+export function keys(value) {
+    if (typeof value !== 'object' || value === null) {
+        return [];
+    }
+    return Object.keys(value);
+}
+/**
+ * Get object values
+ * Usage: {{ {a: 1, b: 2} | values }} → [1, 2]
+ */
+export function values(value) {
+    if (typeof value !== 'object' || value === null) {
+        return [];
+    }
+    return Object.values(value);
+}
+/**
+ * Get object entries (key-value pairs)
+ * Usage: {{ {a: 1, b: 2} | entries }} → [['a', 1], ['b', 2]]
+ */
+export function entries(value) {
+    if (typeof value !== 'object' || value === null) {
+        return [];
+    }
+    return Object.entries(value);
+}
+/**
+ * Pick specific keys from object
+ * Usage: {{ {a: 1, b: 2, c: 3} | pick('a', 'c') }} → {a: 1, c: 3}
+ */
+export function pick(value, ...keysToPick) {
+    if (typeof value !== 'object' || value === null) {
+        return {};
+    }
+    const obj = value;
+    const result = {};
+    for (const key of keysToPick) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Omit specific keys from object
+ * Usage: {{ {a: 1, b: 2, c: 3} | omit('b') }} → {a: 1, c: 3}
+ */
+export function omit(value, ...keysToOmit) {
+    if (typeof value !== 'object' || value === null) {
+        return {};
+    }
+    const obj = value;
+    const result = {};
+    const omitSet = new Set(keysToOmit);
+    for (const [key, val] of Object.entries(obj)) {
+        if (!omitSet.has(key)) {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+/**
+ * Merge objects
+ * Usage: {{ {a: 1} | merge({b: 2}) }} → {a: 1, b: 2}
+ */
+export function merge(value, ...objects) {
+    if (typeof value !== 'object' || value === null) {
+        return {};
+    }
+    let result = { ...value };
+    for (const obj of objects) {
+        if (typeof obj === 'object' && obj !== null) {
+            result = { ...result, ...obj };
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Date Helpers
+// ============================================================================
+/**
+ * Get current timestamp
+ * Usage: {{ now() }} → 1706745600000
+ */
+export function now() {
+    return Date.now();
+}
+/**
+ * Format date
+ * Usage: {{ timestamp | format_date('YYYY-MM-DD') }} → "2025-01-31"
+ */
+export function format_date(value, format = 'YYYY-MM-DD') {
+    let date;
+    if (value instanceof Date) {
+        date = value;
+    }
+    else if (typeof value === 'string' || typeof value === 'number') {
+        date = new Date(value);
+    }
+    else {
+        date = new Date();
+    }
+    if (isNaN(date.getTime())) {
+        return 'Invalid Date';
+    }
+    // Simple date formatting
+    let formatted = format;
+    formatted = formatted.replace('YYYY', date.getFullYear().toString());
+    formatted = formatted.replace('MM', String(date.getMonth() + 1).padStart(2, '0'));
+    formatted = formatted.replace('DD', String(date.getDate()).padStart(2, '0'));
+    formatted = formatted.replace('HH', String(date.getHours()).padStart(2, '0'));
+    formatted = formatted.replace('mm', String(date.getMinutes()).padStart(2, '0'));
+    formatted = formatted.replace('ss', String(date.getSeconds()).padStart(2, '0'));
+    return formatted;
+}
+/**
+ * Add days to date
+ * Usage: {{ timestamp | add_days(7) }} → timestamp + 7 days
+ */
+export function add_days(value, days) {
+    const date = new Date(value);
+    if (isNaN(date.getTime()))
+        return 0;
+    date.setDate(date.getDate() + days);
+    return date.getTime();
+}
+/**
+ * Subtract days from date
+ * Usage: {{ timestamp | subtract_days(7) }} → timestamp - 7 days
+ */
+export function subtract_days(value, days) {
+    const date = new Date(value);
+    if (isNaN(date.getTime()))
+        return 0;
+    date.setDate(date.getDate() - days);
+    return date.getTime();
+}
+/**
+ * Get date difference in days (date1 - date2)
+ * Usage: {{ date1 | diff_days(date2) }} → number of days
+ */
+export function diff_days(value, compareDate) {
+    const date1 = new Date(value);
+    const date2 = new Date(compareDate);
+    if (isNaN(date1.getTime()) || isNaN(date2.getTime()))
+        return 0;
+    const diffMs = date1.getTime() - date2.getTime();
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+// ============================================================================
+// Logic Helpers
+// ============================================================================
+/**
+ * Return default value if input is null/undefined
+ * Usage: {{ null | default('N/A') }} → "N/A"
+ */
+export function defaultValue(value, defaultVal) {
+    if (value === null || value === undefined) {
+        return defaultVal;
+    }
+    return value;
+}
+/**
+ * Return first truthy value
+ * Usage: {{ null | or('fallback') }} → "fallback"
+ */
+export function or(value, ...alternatives) {
+    if (value)
+        return value;
+    for (const alt of alternatives) {
+        if (alt)
+            return alt;
+    }
+    return null;
+}
+/**
+ * Check if all values are truthy
+ * Usage: {{ true | and(1, 'value') }} → true
+ */
+export function and(value, ...values) {
+    if (!value)
+        return false;
+    for (const v of values) {
+        if (!v)
+            return false;
+    }
+    return true;
+}
+/**
+ * Negate boolean value
+ * Usage: {{ true | not }} → false
+ */
+export function not(value) {
+    return !value;
+}
+/**
+ * Ternary operator
+ * Usage: {{ condition | ternary('yes', 'no') }}
+ */
+export function ternary(condition, trueVal, falseVal) {
+    return condition ? trueVal : falseVal;
+}
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Check if value is array
+ * Usage: {{ value | is_array }} → true/false
+ */
+export function is_array(value) {
+    return Array.isArray(value);
+}
+/**
+ * Check if value is object
+ * Usage: {{ value | is_object }} → true/false
+ */
+export function is_object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Check if value is string
+ * Usage: {{ value | is_string }} → true/false
+ */
+export function is_string(value) {
+    return typeof value === 'string';
+}
+/**
+ * Check if value is number
+ * Usage: {{ value | is_number }} → true/false
+ */
+export function is_number(value) {
+    return typeof value === 'number' && !isNaN(value);
+}
+/**
+ * Check if value is empty
+ * Usage: {{ value | is_empty }} → true/false
+ */
+export function is_empty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length === 0;
+    return false;
+}
+/**
+ * Check if value is null
+ * Usage: {{ value | is_null }} → true/false
+ */
+export function is_null(value) {
+    return value === null;
+}
+// ============================================================================
+// JSON Helpers
+// ============================================================================
+/**
+ * Parse JSON string
+ * Usage: {{ '{"a":1}' | parse_json }} → {a: 1}
+ */
+export function parse_json(value) {
+    try {
+        return JSON.parse(String(value));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stringify to JSON
+ * Usage: {{ {a: 1} | to_json }} → '{"a":1}'
+ */
+export function to_json(value, pretty = false) {
+    return JSON.stringify(value, null, pretty ? 2 : 0);
+}
+// ============================================================================
+// Math Helpers
+// ============================================================================
+/**
+ * Absolute value
+ * Usage: {{ -5 | abs }} → 5
+ */
+export function abs(value) {
+    return Math.abs(Number(value));
+}
+/**
+ * Round to nearest integer
+ * Usage: {{ 3.7 | round }} → 4
+ */
+export function round(value, decimals = 0) {
+    const num = Number(value);
+    const multiplier = Math.pow(10, decimals);
+    return Math.round(num * multiplier) / multiplier;
+}
+/**
+ * Round down
+ * Usage: {{ 3.7 | floor }} → 3
+ */
+export function floor(value) {
+    return Math.floor(Number(value));
+}
+/**
+ * Round up
+ * Usage: {{ 3.1 | ceil }} → 4
+ */
+export function ceil(value) {
+    return Math.ceil(Number(value));
+}
+/**
+ * Get minimum value
+ * Usage: {{ [1, 2, 3] | min }} → 1
+ * Usage: {{ 5 | min(3) }} → 3
+ */
+export function min(value, ...values) {
+    if (Array.isArray(value)) {
+        return Math.min(...value.map(v => Number(v)));
+    }
+    const nums = [Number(value), ...values.map(v => Number(v))];
+    return Math.min(...nums);
+}
+/**
+ * Get maximum value
+ * Usage: {{ [1, 2, 3] | max }} → 3
+ * Usage: {{ 3 | max(5) }} → 5
+ */
+export function max(value, ...values) {
+    if (Array.isArray(value)) {
+        return Math.max(...value.map(v => Number(v)));
+    }
+    const nums = [Number(value), ...values.map(v => Number(v))];
+    return Math.max(...nums);
+}
+// ============================================================================
+// Helper Registry
+// ============================================================================
+/**
+ * Global registry of all helper functions
+ */
+export const HELPER_REGISTRY = {
+    // String helpers
+    split: split,
+    join: join,
+    trim: trim,
+    upper: upper,
+    lower: lower,
+    title: title,
+    capitalize: capitalize,
+    slugify: slugify,
+    prefix: prefix,
+    suffix: suffix,
+    replace: replace,
+    truncate: truncate,
+    substring: substring,
+    contains: contains,
+    // Array helpers
+    first: first,
+    last: last,
+    nth: nth,
+    count: count,
+    sum: sum,
+    unique: unique,
+    flatten: flatten,
+    reverse: reverse,
+    sort: sort,
+    slice: slice,
+    // Object helpers
+    path: path,
+    keys: keys,
+    values: values,
+    entries: entries,
+    pick: pick,
+    omit: omit,
+    merge: merge,
+    // Date helpers
+    now: now,
+    format_date: format_date,
+    add_days: add_days,
+    subtract_days: subtract_days,
+    diff_days: diff_days,
+    // Logic helpers
+    default: defaultValue,
+    or: or,
+    and: and,
+    not: not,
+    ternary: ternary,
+    // Validation helpers
+    is_array: is_array,
+    is_object: is_object,
+    is_string: is_string,
+    is_number: is_number,
+    is_empty: is_empty,
+    is_null: is_null,
+    // JSON helpers
+    parse_json: parse_json,
+    to_json: to_json,
+    // Math helpers
+    abs: abs,
+    round: round,
+    floor: floor,
+    ceil: ceil,
+    min: min,
+    max: max,
+};
+/**
+ * Apply a helper function to a value
+ */
+export function applyHelper(helperName, value, args) {
+    const helper = HELPER_REGISTRY[helperName];
+    if (!helper) {
+        throw new Error(`Unknown helper function: ${helperName}`);
+    }
+    return helper(value, ...args);
+}
+/**
+ * Check if a helper exists
+ */
+export function hasHelper(helperName) {
+    return helperName in HELPER_REGISTRY;
+}
+//# sourceMappingURL=expression-helpers.js.map