@wcstack/state 1.3.11

package/dist/filters/builtinFilters.js

@@ -0,0 +1,716 @@
+/**
+ * builtinFilters.ts
+ *
+ * Implementation file for built-in filter functions available in Structive.
+ *
+ * Main responsibilities:
+ * - Provides filters for conversion, comparison, formatting, and validation of numbers, strings, dates, booleans, etc.
+ * - Defines functions with options for each filter name, enabling flexible use during binding
+ * - Designed for common use as both input and output filters
+ *
+ * Design points:
+ * - Comprehensive coverage of diverse filters: eq, ne, lt, gt, inc, fix, locale, uc, lc, cap, trim, slice, pad, int, float, round, date, time, ymd, falsy, truthy, defaults, boolean, number, string, null, etc.
+ * - Rich type checking and error handling for option values
+ * - Centralized management of filter functions with FilterWithOptions type, easy to extend
+ * - Dynamic retrieval of filter functions from filter names and options via builtinFilterFn
+ */
+import { config } from "../config.js";
+import { raiseError } from "../raiseError.js";
+import { optionMustBeNumber, optionsRequired, valueMustBeBoolean, valueMustBeDate, valueMustBeNumber } from "./errorMessages.js";
+function validateNumberString(value) {
+    if (!value || isNaN(Number(value))) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Equality filter - compares value with option.
+ *
+ * @param options - Array with comparison value as first element
+ * @returns Filter function that returns boolean
+ */
+const eq = (options) => {
+    const opt = options?.[0] ?? optionsRequired('eq');
+    return (value) => {
+        // Align types for comparison
+        if (typeof value === 'number') {
+            if (!validateNumberString(opt)) {
+                optionMustBeNumber('eq');
+            }
+            return value === Number(opt);
+        }
+        if (typeof value === 'string') {
+            return value === opt;
+        }
+        // Strict equality for others
+        return value === opt;
+    };
+};
+/**
+ * Inequality filter - compares value with option.
+ *
+ * @param options - Array with comparison value as first element
+ * @returns Filter function that returns boolean
+ */
+const ne = (options) => {
+    const opt = options?.[0] ?? optionsRequired('ne');
+    return (value) => {
+        // Align types for comparison
+        if (typeof value === 'number') {
+            if (!validateNumberString(opt)) {
+                optionMustBeNumber('ne');
+            }
+            return value !== Number(opt);
+        }
+        if (typeof value === 'string') {
+            return value !== opt;
+        }
+        // Strict equality for others
+        return value !== opt;
+    };
+};
+/**
+ * Boolean NOT filter - inverts boolean value.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns inverted boolean
+ */
+const not = (_options) => {
+    return (value) => {
+        if (typeof value !== 'boolean') {
+            valueMustBeBoolean('not');
+        }
+        return !value;
+    };
+};
+/**
+ * Less than filter - checks if value is less than option.
+ *
+ * @param options - Array with comparison number as first element
+ * @returns Filter function that returns boolean
+ */
+const lt = (options) => {
+    const opt = options?.[0] ?? optionsRequired('lt');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('lt');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('lt');
+        }
+        return value < Number(opt);
+    };
+};
+/**
+ * Less than or equal filter - checks if value is less than or equal to option.
+ *
+ * @param options - Array with comparison number as first element
+ * @returns Filter function that returns boolean
+ */
+const le = (options) => {
+    const opt = options?.[0] ?? optionsRequired('le');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('le');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('le');
+        }
+        return value <= Number(opt);
+    };
+};
+/**
+ * Greater than filter - checks if value is greater than option.
+ *
+ * @param options - Array with comparison number as first element
+ * @returns Filter function that returns boolean
+ */
+const gt = (options) => {
+    const opt = options?.[0] ?? optionsRequired('gt');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('gt');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('gt');
+        }
+        return value > Number(opt);
+    };
+};
+/**
+ * Greater than or equal filter - checks if value is greater than or equal to option.
+ *
+ * @param options - Array with comparison number as first element
+ * @returns Filter function that returns boolean
+ */
+const ge = (options) => {
+    const opt = options?.[0] ?? optionsRequired('ge');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('ge');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('ge');
+        }
+        return value >= Number(opt);
+    };
+};
+/**
+ * Increment filter - adds option value to input value.
+ *
+ * @param options - Array with increment number as first element
+ * @returns Filter function that returns incremented number
+ */
+const inc = (options) => {
+    const opt = options?.[0] ?? optionsRequired('inc');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('inc');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('inc');
+        }
+        return value + Number(opt);
+    };
+};
+/**
+ * Decrement filter - subtracts option value from input value.
+ *
+ * @param options - Array with decrement number as first element
+ * @returns Filter function that returns decremented number
+ */
+const dec = (options) => {
+    const opt = options?.[0] ?? optionsRequired('dec');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('dec');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('dec');
+        }
+        return value - Number(opt);
+    };
+};
+/**
+ * Multiply filter - multiplies value by option.
+ *
+ * @param options - Array with multiplier number as first element
+ * @returns Filter function that returns multiplied number
+ */
+const mul = (options) => {
+    const opt = options?.[0] ?? optionsRequired('mul');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('mul');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('mul');
+        }
+        return value * Number(opt);
+    };
+};
+/**
+ * Divide filter - divides value by option.
+ *
+ * @param options - Array with divisor number as first element
+ * @returns Filter function that returns divided number
+ */
+const div = (options) => {
+    const opt = options?.[0] ?? optionsRequired('div');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('div');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('div');
+        }
+        return value / Number(opt);
+    };
+};
+/**
+ * Modulo filter - returns remainder of division.
+ *
+ * @param options - Array with divisor number as first element
+ * @returns Filter function that returns remainder
+ */
+const mod = (options) => {
+    const opt = options?.[0] ?? optionsRequired('mod');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('mod');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('mod');
+        }
+        return value % Number(opt);
+    };
+};
+/**
+ * Fixed decimal filter - formats number to fixed decimal places.
+ *
+ * @param options - Array with decimal places as first element (default: 0)
+ * @returns Filter function that returns formatted string
+ */
+const fix = (options) => {
+    const opt = options?.[0] ?? "0";
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('fix');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('fix');
+        }
+        return value.toFixed(Number(opt));
+    };
+};
+/**
+ * Locale number filter - formats number according to locale.
+ *
+ * @param options - Array with locale string as first element (default: config.locale)
+ * @returns Filter function that returns localized number string
+ */
+const locale = (options) => {
+    const opt = options?.[0] ?? config.locale;
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('locale');
+        }
+        return value.toLocaleString(opt);
+    };
+};
+/**
+ * Uppercase filter - converts string to uppercase.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns uppercase string
+ */
+const uc = (_options) => {
+    return (value) => {
+        return String(value).toUpperCase();
+    };
+};
+/**
+ * Lowercase filter - converts string to lowercase.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns lowercase string
+ */
+const lc = (_options) => {
+    return (value) => {
+        return String(value).toLowerCase();
+    };
+};
+/**
+ * Capitalize filter - capitalizes first character of string.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns capitalized string
+ */
+const cap = (_options) => {
+    return (value) => {
+        const v = String(value);
+        if (v.length === 0) {
+            return v;
+        }
+        if (v.length === 1) {
+            return v.toUpperCase();
+        }
+        return v.charAt(0).toUpperCase() + v.slice(1);
+    };
+};
+/**
+ * Trim filter - removes whitespace from both ends of string.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns trimmed string
+ */
+const trim = (_options) => {
+    return (value) => {
+        return String(value).trim();
+    };
+};
+/**
+ * Slice filter - extracts portion of string from specified index.
+ *
+ * @param options - Array with start index and optional end index
+ * @returns Filter function that returns sliced string
+ */
+const slice = (options) => {
+    const numberedOpts = [];
+    const opt1 = options?.[0] ?? optionsRequired('slice');
+    if (!validateNumberString(opt1)) {
+        optionMustBeNumber('slice');
+    }
+    numberedOpts.push(Number(opt1));
+    const opt2 = options?.[1];
+    if (typeof opt2 !== 'undefined') {
+        if (!validateNumberString(opt2)) {
+            optionMustBeNumber('slice');
+        }
+        numberedOpts.push(Number(opt2));
+    }
+    return (value) => {
+        return String(value).slice(...numberedOpts);
+    };
+};
+/**
+ * Substring filter - extracts substring from specified position and length.
+ *
+ * @param options - Array with start index and length
+ * @returns Filter function that returns substring
+ */
+const substr = (options) => {
+    const opt1 = options?.[0] ?? optionsRequired('substr');
+    if (!validateNumberString(opt1)) {
+        optionMustBeNumber('substr');
+    }
+    const opt2 = options?.[1] ?? optionsRequired('substr');
+    if (!validateNumberString(opt2)) {
+        optionMustBeNumber('substr');
+    }
+    return (value) => {
+        return String(value).substr(Number(opt1), Number(opt2));
+    };
+};
+/**
+ * Pad filter - pads string to specified length from start.
+ *
+ * @param options - Array with target length and pad string (default: '0')
+ * @returns Filter function that returns padded string
+ */
+const pad = (options) => {
+    const opt1 = options?.[0] ?? optionsRequired('pad');
+    if (!validateNumberString(opt1)) {
+        optionMustBeNumber('pad');
+    }
+    const opt2 = options?.[1] ?? '0';
+    return (value) => {
+        return String(value).padStart(Number(opt1), opt2);
+    };
+};
+/**
+ * Repeat filter - repeats string specified number of times.
+ *
+ * @param options - Array with repeat count as first element
+ * @returns Filter function that returns repeated string
+ */
+const rep = (options) => {
+    const opt = options?.[0] ?? optionsRequired('rep');
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('rep');
+    }
+    return (value) => {
+        return String(value).repeat(Number(opt));
+    };
+};
+/**
+ * Reverse filter - reverses character order in string.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns reversed string
+ */
+const rev = (_options) => {
+    return (value) => {
+        return String(value).split('').reverse().join('');
+    };
+};
+/**
+ * Integer filter - parses value to integer.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns integer
+ */
+const int = (_options) => {
+    return (value) => {
+        return parseInt(String(value), 10);
+    };
+};
+/**
+ * Float filter - parses value to floating point number.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns float
+ */
+const float = (_options) => {
+    return (value) => {
+        return parseFloat(String(value));
+    };
+};
+/**
+ * Round filter - rounds number to specified decimal places.
+ *
+ * @param options - Array with decimal places as first element (default: 0)
+ * @returns Filter function that returns rounded number
+ */
+const round = (options) => {
+    const opt = options?.[0] ?? '0';
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('round');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('round');
+        }
+        const optValue = Math.pow(10, Number(opt));
+        return Math.round(value * optValue) / optValue;
+    };
+};
+/**
+ * Floor filter - rounds number down to specified decimal places.
+ *
+ * @param options - Array with decimal places as first element (default: 0)
+ * @returns Filter function that returns floored number
+ */
+const floor = (options) => {
+    const opt = options?.[0] ?? '0';
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('floor');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('floor');
+        }
+        const optValue = Math.pow(10, Number(opt));
+        return Math.floor(value * optValue) / optValue;
+    };
+};
+/**
+ * Ceiling filter - rounds number up to specified decimal places.
+ *
+ * @param options - Array with decimal places as first element (default: 0)
+ * @returns Filter function that returns ceiled number
+ */
+const ceil = (options) => {
+    const opt = options?.[0] ?? '0';
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('ceil');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('ceil');
+        }
+        const optValue = Math.pow(10, Number(opt));
+        return Math.ceil(value * optValue) / optValue;
+    };
+};
+/**
+ * Percent filter - formats number as percentage string.
+ *
+ * @param options - Array with decimal places as first element (default: 0)
+ * @returns Filter function that returns percentage string with '%'
+ */
+const percent = (options) => {
+    const opt = options?.[0] ?? '0';
+    if (!validateNumberString(opt)) {
+        optionMustBeNumber('percent');
+    }
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('percent');
+        }
+        return `${(value * 100).toFixed(Number(opt))}%`;
+    };
+};
+/**
+ * Date filter - formats Date object as localized date string.
+ *
+ * @param options - Array with locale string as first element (default: config.locale)
+ * @returns Filter function that returns date string
+ */
+const date = (options) => {
+    const opt = options?.[0] ?? config.locale;
+    return (value) => {
+        if (!(value instanceof Date)) {
+            valueMustBeDate('date');
+        }
+        return value.toLocaleDateString(opt);
+    };
+};
+/**
+ * Time filter - formats Date object as localized time string.
+ *
+ * @param options - Array with locale string as first element (default: config.locale)
+ * @returns Filter function that returns time string
+ */
+const time = (options) => {
+    const opt = options?.[0] ?? config.locale;
+    return (value) => {
+        if (!(value instanceof Date)) {
+            valueMustBeDate('time');
+        }
+        return value.toLocaleTimeString(opt);
+    };
+};
+/**
+ * DateTime filter - formats Date object as localized date and time string.
+ *
+ * @param options - Array with locale string as first element (default: config.locale)
+ * @returns Filter function that returns datetime string
+ */
+const datetime = (options) => {
+    const opt = options?.[0] ?? config.locale;
+    return (value) => {
+        if (!(value instanceof Date)) {
+            valueMustBeDate('datetime');
+        }
+        return value.toLocaleString(opt);
+    };
+};
+/**
+ * Year-Month-Day filter - formats Date object as YYYY-MM-DD string.
+ *
+ * @param options - Array with separator string as first element (default: '-')
+ * @returns Filter function that returns formatted date string
+ */
+const ymd = (options) => {
+    const opt = options?.[0] ?? '-';
+    return (value) => {
+        if (!(value instanceof Date)) {
+            valueMustBeDate('ymd');
+        }
+        const year = value.getFullYear().toString();
+        const month = (value.getMonth() + 1).toString().padStart(2, '0');
+        const day = value.getDate().toString().padStart(2, '0');
+        return `${year}${opt}${month}${opt}${day}`;
+    };
+};
+/**
+ * Falsy filter - checks if value is falsy.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns true for false/null/undefined/0/''/NaN
+ */
+const falsy = (_options) => {
+    return (value) => value === false || value === null || value === undefined || value === 0 || value === '' || Number.isNaN(value);
+};
+/**
+ * Truthy filter - checks if value is truthy.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns true for non-falsy values
+ */
+const truthy = (_options) => {
+    return (value) => value !== false && value !== null && value !== undefined && value !== 0 && value !== '' && !Number.isNaN(value);
+};
+/**
+ * Default filter - returns default value if input is falsy.
+ *
+ * @param options - Array with default value as first element
+ * @returns Filter function that returns value or default
+ */
+const defaults = (options) => {
+    const opt = options?.[0] ?? optionsRequired('defaults');
+    return (value) => {
+        if (value === false || value === null || value === undefined || value === 0 || value === '' || Number.isNaN(value)) {
+            return opt;
+        }
+        return value;
+    };
+};
+/**
+ * Boolean filter - converts value to boolean.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns boolean
+ */
+const boolean = (_options) => {
+    return (value) => {
+        return Boolean(value);
+    };
+};
+/**
+ * Number filter - converts value to number.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns number
+ */
+const number = (_options) => {
+    return (value) => {
+        return Number(value);
+    };
+};
+/**
+ * String filter - converts value to string.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns string
+ */
+const string = (_options) => {
+    return (value) => {
+        return String(value);
+    };
+};
+/**
+ * Null filter - converts empty string to null.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns null for empty string, otherwise original value
+ */
+const _null = (_options) => {
+    return (value) => {
+        return (value === "") ? null : value;
+    };
+};
+const builtinFilters = {
+    "eq": eq,
+    "ne": ne,
+    "not": not,
+    "lt": lt,
+    "le": le,
+    "gt": gt,
+    "ge": ge,
+    "inc": inc,
+    "dec": dec,
+    "mul": mul,
+    "div": div,
+    "mod": mod,
+    "fix": fix,
+    "locale": locale,
+    "uc": uc,
+    "lc": lc,
+    "cap": cap,
+    "trim": trim,
+    "slice": slice,
+    "substr": substr,
+    "pad": pad,
+    "rep": rep,
+    "rev": rev,
+    "int": int,
+    "float": float,
+    "round": round,
+    "floor": floor,
+    "ceil": ceil,
+    "percent": percent,
+    "date": date,
+    "time": time,
+    "datetime": datetime,
+    "ymd": ymd,
+    "falsy": falsy,
+    "truthy": truthy,
+    "defaults": defaults,
+    "boolean": boolean,
+    "number": number,
+    "string": string,
+    "null": _null,
+};
+export const outputBuiltinFilters = builtinFilters;
+export const inputBuiltinFilters = builtinFilters;
+export const builtinFiltersByFilterIOType = {
+    "input": inputBuiltinFilters,
+    "output": outputBuiltinFilters,
+};
+/**
+ * Retrieves built-in filter function by name and options.
+ *
+ * @param name - Filter name
+ * @param options - Array of option strings
+ * @returns Function that takes FilterWithOptions and returns filter function
+ */
+export const builtinFilterFn = (name, options) => (filters) => {
+    const filter = filters[name];
+    if (!filter) {
+        raiseError(`filter not found: ${name}`);
+    }
+    return filter(options);
+};
+//# sourceMappingURL=builtinFilters.js.map