@halleyassist/rule-templater 0.0.16 → 0.0.18

package/README.md

@@ -121,6 +121,8 @@ const prepared = parsed.prepare({
 - **round**: Round number to nearest integer
 - **floor**: Round number down
 - **ceil**: Round number up
+- **humanise_list**: Join array values into natural language, optionally with a custom joiner like `humanise_list("or")`
+- **humanise_time**: Convert seconds into a single human-readable unit like `1 hour`; optionally round down to a minimum unit such as `humanise_time("minute")` or `humanise_time("min")`
 - **time_start**: Extract `from` from `time period` / `time period ago` and convert to `time value`
 - **time_end**: Extract `to` from `time period` / `time period ago` and convert to `time value`
 
@@ -140,6 +142,14 @@ const prepared = parsed.prepare({
 // Chaining filters
 '${text|trim|upper}' with text='  hello  ' → HELLO
 
+// Humanise arrays
+'${names|humanise_list}' with names=['a','b','c'] → a, b and c
+'${names|humanise_list("or")}' with names=['a','b','c'] → a, b or c
+
+// Humanise time from seconds
+'${duration|humanise_time}' with duration=3600 → 1 hour
+'${duration|humanise_time("minute")}' with duration=71 → 1 minute
+
 // Time period conversion
 '${window|time_start}' with window={from:'08:00',to:'12:00'} → 08:00
 ```
@@ -232,7 +242,7 @@ This is useful for comparing against a hub's list of available functions to ensu
 
 ### `ruleTemplate.validate(variables)`
 
-Validates that all required variables are provided and have valid types.
+Validates that all required variables are provided, have valid types, and reference only known template filters.
 
 **Parameters:**
 - `variables` (object): Object mapping variable names to their values and types
@@ -243,6 +253,7 @@ Validates that all required variables are provided and have valid types.
 **Returns:** Object with:
 - `valid` (boolean): Whether validation passed
 - `errors` (array): Array of error messages (empty if valid)
+- `warnings` (array): Array of non-fatal warnings (empty if none)
 
 ### `ruleTemplate.prepare(variables)`
 
@@ -272,6 +283,10 @@ Extracts variables from a general string template.
 
 Prepares a general string template by replacing `${...}` placeholders with values and applying filters.
 
+### `generalTemplate.validate()`
+
+Validates the template itself and reports any unknown filters used in `${...}` chains.
+
 ### `RuleTemplate.validateVariableNode(astNode, variableType)` (Static)
 
 Helper method to validate that an AST node matches the expected variable type.

package/dist/rule-templater.browser.js

@@ -3888,11 +3888,13 @@ class RuleTemplate {
         
         // Extract filters
         const filters = [];
+        const filterCalls = [];
         for (const child of templateExpr.children || []) {
             if (child.type === 'template_filter_call') {
-                const filterName = this._extractFilterName(child);
-                if (filterName) {
-                    filters.push(filterName);
+                const filterCall = this._extractFilterCall(child);
+                if (filterCall) {
+                    filters.push(filterCall.name);
+                    filterCalls.push(filterCall);
                 }
             }
         }
@@ -3901,38 +3903,128 @@ class RuleTemplate {
         const start = node.start;
         const end = node.end;
         
-        return { name, filters, start, end };
+        return { name, filters, filterCalls, start, end };
     }
 
     /**
-     * Extract filter name from template_filter_call node
+     * Extract filter call from template_filter_call node
      * @private
      */
-    _extractFilterName(node) {
+    _extractFilterCall(node) {
         const filterNameNode = node.children?.find(c => c.type === 'template_filter_name');
         if (!filterNameNode || !filterNameNode.text) return null;
-        
-        return filterNameNode.text.trim();
+
+        const argsNode = node.children?.find(c => c.type === 'template_filter_args');
+
+        return {
+            name: filterNameNode.text.trim(),
+            args: this._extractFilterArgs(argsNode)
+        };
+    }
+
+    _extractFilterArgs(node) {
+        if (!node || !Array.isArray(node.children)) {
+            return [];
+        }
+
+        return node.children
+            .filter(child => child.type === 'template_filter_arg')
+            .map(child => this._extractFilterArgValue(child));
+    }
+
+    _extractFilterArgValue(node) {
+        if (!node || !Array.isArray(node.children) || node.children.length === 0) {
+            return this._normalizeFilterArgText(node?.text?.trim() || '');
+        }
+
+        const child = node.children[0];
+        if (!child) {
+            return this._normalizeFilterArgText(node.text?.trim() || '');
+        }
+
+        if (child.type === 'value' && Array.isArray(child.children) && child.children.length > 0) {
+            return this._extractFilterArgValue(child);
+        }
+
+        if (child.type === 'string') {
+            try {
+                return JSON.parse(child.text);
+            } catch (error) {
+                return this._normalizeFilterArgText(child.text);
+            }
+        }
+
+        if (child.type === 'number') {
+            return Number(child.text);
+        }
+
+        if (child.type === 'true') {
+            return true;
+        }
+
+        if (child.type === 'false') {
+            return false;
+        }
+
+        if (child.type === 'null') {
+            return null;
+        }
+
+        return this._normalizeFilterArgText(child.text?.trim() || node.text?.trim() || '');
+    }
+
+    _normalizeFilterArgText(text) {
+        const normalizedText = String(text).trim();
+
+        if ((normalizedText.startsWith('"') && normalizedText.endsWith('"')) || (normalizedText.startsWith("'") && normalizedText.endsWith("'"))) {
+            return normalizedText.slice(1, -1);
+        }
+
+        return normalizedText;
     }
 
     /**
      * Validate variable types against the AST
      * @param {Object} variables - Object mapping variable names to {type} objects
-     * @returns {Object} Object with validation results: {valid: boolean, errors: []}
+     * @param {Object} [functionBlob] - Optional HalleyFunctionBlob used for non-fatal function warnings
+     * @returns {Object} Object with validation results: {valid: boolean, errors: [], warnings: []}
      */
-    validate(variables) {
+    validate(variables, functionBlob) {
         if (!variables || typeof variables !== 'object') {
             return {
                 valid: false,
-                errors: ['Variables must be provided as an object']
+                errors: ['Variables must be provided as an object'],
+                warnings: []
             };
         }
 
         const errors = [];
-        const extractedVars = this.extractVariables();
+        const warnings = [];
+        const extractedVars = this._extractTemplateVariables();
+        const seenVariables = new Set();
+        const seenFilterErrors = new Set();
         
         for (const varInfo of extractedVars) {
             const varName = varInfo.name;
+
+            for (const filter of (varInfo.filterCalls || varInfo.filters || [])) {
+                const filterName = typeof filter === 'string' ? filter : filter?.name;
+                if (filterName && TemplateFilters[filterName]) {
+                    continue;
+                }
+
+                const errorMessage = `Unknown filter '${filterName || filter}' for variable '${varName}'`;
+                if (!seenFilterErrors.has(errorMessage)) {
+                    errors.push(errorMessage);
+                    seenFilterErrors.add(errorMessage);
+                }
+            }
+
+            if (seenVariables.has(varName)) {
+                continue;
+            }
+
+            seenVariables.add(varName);
             
             // Check if variable is provided
             if (!variables.hasOwnProperty(varName)) {
@@ -3961,13 +4053,74 @@ class RuleTemplate {
                 }
             }
         }
+
+        if (functionBlob && typeof functionBlob.validate === 'function') {
+            for (const functionCall of this._extractFunctionCalls()) {
+                warnings.push(...functionBlob.validate(functionCall.name, functionCall.arguments));
+            }
+        }
         
         return {
             valid: errors.length === 0,
-            errors
+            errors,
+            warnings
         };
     }
 
+    _extractFunctionCalls() {
+        const functionCalls = [];
+
+        const traverse = (node) => {
+            if (!node) return;
+
+            if (node.type === 'fcall') {
+                const functionName = node.children?.find(c => c.type === 'fname')?.text?.trim();
+                const argumentsNode = node.children?.find(c => c.type === 'arguments');
+                if (functionName) {
+                    functionCalls.push({
+                        name: functionName,
+                        arguments: argumentsNode?.children
+                            ?.filter(c => c.type === 'argument')
+                            .map(c => c.text) || []
+                    });
+                }
+            }
+
+            if (node.children) {
+                for (const child of node.children) {
+                    traverse(child);
+                }
+            }
+        };
+
+        traverse(this.ast);
+        return functionCalls;
+    }
+
+    _extractTemplateVariables() {
+        const variables = [];
+
+        const traverse = (node) => {
+            if (!node) return;
+
+            if (node.type === 'template_value') {
+                const variableInfo = this._extractVariableFromNode(node);
+                if (variableInfo) {
+                    variables.push(variableInfo);
+                }
+            }
+
+            if (node.children) {
+                for (const child of node.children) {
+                    traverse(child);
+                }
+            }
+        };
+
+        traverse(this.ast);
+        return variables;
+    }
+
     /**
      * Prepare the template by replacing variables with their values
      * Rebuilds from AST by iterating through children
@@ -4070,12 +4223,15 @@ class RuleTemplate {
         
         // Apply filters if present
         if (templateInfo.filters && templateInfo.filters.length > 0) {
-            for (const filterName of templateInfo.filters) {
-                if (!TemplateFilters[filterName]) {
-                    throw new Error(`Unknown filter '${filterName}'`);
+            for (const filter of (templateInfo.filterCalls || templateInfo.filters)) {
+                const filterName = typeof filter === 'string' ? filter : filter?.name;
+                const filterArgs = typeof filter === 'string' ? [] : (Array.isArray(filter?.args) ? filter.args : []);
+
+                if (!filterName || !TemplateFilters[filterName]) {
+                    throw new Error(`Unknown filter '${filterName || filter}'`);
                 }
-               
-                TemplateFilters[filterName](varData);
+
+                TemplateFilters[filterName](varData, ...filterArgs);
             }
         }
 
@@ -4153,6 +4309,31 @@ module.exports = RuleTemplate;
 Template filters are functions that transform variable values.
 They are applied in the template syntax as ${variable|filter} or ${variable|filter1|filter2}
 */
+const HUMANISE_TIME_UNITS = [
+    { name: 'year', seconds: 31536000, aliases: ['year', 'years', 'yr', 'yrs', 'y'] },
+    { name: 'month', seconds: 2592000, aliases: ['month', 'months', 'mo', 'mos'] },
+    { name: 'week', seconds: 604800, aliases: ['week', 'weeks', 'wk', 'wks', 'w'] },
+    { name: 'day', seconds: 86400, aliases: ['day', 'days', 'd'] },
+    { name: 'hour', seconds: 3600, aliases: ['hour', 'hours', 'hr', 'hrs', 'h'] },
+    { name: 'minute', seconds: 60, aliases: ['minute', 'minutes', 'min', 'mins'] },
+    { name: 'second', seconds: 1, aliases: ['second', 'seconds', 'sec', 'secs', 's'] }
+];
+
+const getHumaniseTimeUnit = minUnit => {
+    if (minUnit === null || minUnit === undefined || minUnit === '') {
+        return null;
+    }
+
+    const normalizedMinUnit = String(minUnit).trim().toLowerCase();
+    const unit = HUMANISE_TIME_UNITS.find(candidate => candidate.aliases.includes(normalizedMinUnit));
+
+    if (!unit) {
+        throw new Error(`Unknown humanise_time min_unit \"${minUnit}\"`);
+    }
+
+    return unit;
+};
+
 const TemplateFilters = {
     // Convert value to JSON string representation
     string: varData => {
@@ -4276,6 +4457,69 @@ const TemplateFilters = {
 
     },
 
+    humanise_list: (varData, joiner = 'and') => {
+        if (typeof varData.value === 'string') {
+            varData.type = 'string';
+            return;
+        }
+
+        if (!Array.isArray(varData.value)) {
+            varData.value = String(varData.value);
+            varData.type = 'string';
+            return;
+        }
+
+        const items = varData.value.map(item => String(item));
+
+        if (items.length === 0) {
+            varData.value = '';
+        } else if (items.length === 1) {
+            [varData.value] = items;
+        } else if (items.length === 2) {
+            varData.value = `${items[0]} ${joiner} ${items[1]}`;
+        } else {
+            varData.value = `${items.slice(0, -1).join(', ')} ${joiner} ${items[items.length - 1]}`;
+        }
+
+        varData.type = 'string';
+
+    },
+
+    humanise_time: (varData, minUnit = null) => {
+        const rawSeconds = Number(varData.value);
+
+        if (isNaN(rawSeconds)) {
+            throw new Error(`Value "${varData.value}" cannot be converted to seconds`);
+        }
+
+        const isNegative = rawSeconds < 0;
+        const absoluteSeconds = Math.abs(rawSeconds);
+        const minimumUnit = getHumaniseTimeUnit(minUnit);
+        const minimumUnitIndex = minimumUnit
+            ? HUMANISE_TIME_UNITS.findIndex(unit => unit.name === minimumUnit.name)
+            : HUMANISE_TIME_UNITS.length - 1;
+        const candidateUnits = HUMANISE_TIME_UNITS.slice(0, minimumUnitIndex + 1);
+        let selectedUnit = candidateUnits.find(unit => absoluteSeconds % unit.seconds === 0);
+        let quantity;
+
+        if (selectedUnit) {
+            quantity = absoluteSeconds / selectedUnit.seconds;
+        } else if (minimumUnit) {
+            selectedUnit = minimumUnit;
+            quantity = Math.floor(absoluteSeconds / selectedUnit.seconds);
+        } else {
+            selectedUnit = HUMANISE_TIME_UNITS[HUMANISE_TIME_UNITS.length - 1];
+            quantity = absoluteSeconds;
+        }
+
+        const signedQuantity = isNegative ? -quantity : quantity;
+        const label = Math.abs(signedQuantity) === 1 ? selectedUnit.name : `${selectedUnit.name}s`;
+
+        varData.value = `${signedQuantity} ${label}`;
+        varData.type = 'string';
+
+    },
+
     // Extract start time from time period/time period ago as time value
     time_start: varData => {
         if (varData.type === 'time period' || varData.type === 'time period ago') {
@@ -4450,12 +4694,15 @@ class VariableValidate {
             throw new Error('Variable data filters must be an array');
         }
 
-        for (const filterName of normalizedVarData.filters) {
-            if (!TemplateFilters[filterName]) {
-                throw new Error(`Unknown filter '${filterName}'`);
+        for (const filter of normalizedVarData.filters) {
+            const filterName = typeof filter === 'string' ? filter : filter?.name;
+            const filterArgs = typeof filter === 'string' ? [] : (Array.isArray(filter?.args) ? filter.args : []);
+
+            if (!filterName || !TemplateFilters[filterName]) {
+                throw new Error(`Unknown filter '${filterName || filter}'`);
             }
 
-            TemplateFilters[filterName](normalizedVarData);
+            TemplateFilters[filterName](normalizedVarData, ...filterArgs);
         }
 
         return normalizedVarData;

package/index.d.ts

@@ -3,9 +3,14 @@ export interface VariablePosition {
     end: number;
 }
 
+export interface TemplateFilterCall {
+    name: string;
+    args: any[];
+}
+
 export interface VariableInfo {
     name: string;
-    filters: string[];
+    filters: Array<string | TemplateFilterCall>;
     positions: VariablePosition[];
 }
 
@@ -26,6 +31,7 @@ export interface Variables {
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
+    warnings: string[];
 }
 
 export interface VariableValidationResult {
@@ -60,6 +66,17 @@ export interface TemplateFiltersType {
     [key: string]: FilterFunction;
 }
 
+export interface HalleyFunctionDefinition {
+    name: string;
+    arguments: string[];
+}
+
+export interface HalleyFunctionBlobData {
+    _schema?: number;
+    version?: string;
+    functions?: HalleyFunctionDefinition[];
+}
+
 export class RuleTemplate {
     ruleTemplateText: string;
     ast: ASTNode;
@@ -90,7 +107,7 @@ export class RuleTemplate {
      * @param variables Object mapping variable names to {value, type} objects
      * @returns Object with validation results: {valid, errors}
      */
-    validate(variables: Variables): ValidationResult;
+    validate(variables: Variables, functionBlob?: HalleyFunctionBlob): ValidationResult;
 
     /**
      * Prepare the template by replacing variables with their values
@@ -122,9 +139,23 @@ export class GeneralTemplate {
 
     extractVariables(): VariableInfo[];
 
+    validate(): ValidationResult;
+
     prepare(variables: Variables): string;
 }
 
+export class HalleyFunctionBlob {
+    _schema?: number;
+    version?: string;
+    functions: HalleyFunctionDefinition[];
+
+    constructor(jsonData: HalleyFunctionBlobData);
+
+    static fromURL(url: string): Promise<HalleyFunctionBlob>;
+
+    validate(functionName: string, variables?: any[]): string[];
+}
+
 export class VariableTemplate {
     templateText: string;
     ast: ASTNode;

package/index.js

@@ -1,5 +1,6 @@
 const RuleTemplate = require('./src/RuleTemplate');
 const GeneralTemplate = require('./src/GeneralTemplate');
+const HalleyFunctionBlob = require('./src/HalleyFunctionBlob');
 const VariableTemplate = require('./src/VariableTemplate');
 const VariableValidate = require('./src/VariableValidate');
 
@@ -9,4 +10,5 @@ module.exports.VariableTypes = RuleTemplate.VariableTypes;
 module.exports.TemplateFilters = RuleTemplate.TemplateFilters;
 module.exports.VariableValidate = VariableValidate;
 module.exports.GeneralTemplate = GeneralTemplate;
+module.exports.HalleyFunctionBlob = HalleyFunctionBlob;
 module.exports.VariableTemplate = VariableTemplate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halleyassist/rule-templater",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "The grammar for HalleyAssist rules",
   "main": "src/RuleTemplate.production.js",
   "browser": "./dist/rule-templater.browser.js",

package/src/GeneralTemplate.js

@@ -1,5 +1,7 @@
 const TemplateFilters = require('./TemplateFilters');
 
+const FILTER_PATTERN = /([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+
 class GeneralTemplate {
     constructor(templateText) {
         this.templateText = templateText;
@@ -52,6 +54,33 @@ class GeneralTemplate {
         return this.getVariables();
     }
 
+    validate() {
+        const errors = [];
+        const warnings = [];
+        const seenFilterErrors = new Set();
+
+        for (const variableInfo of this.getVariables()) {
+            for (const filter of variableInfo.filters || []) {
+                const filterName = typeof filter === 'string' ? filter : filter?.name;
+                if (filterName && TemplateFilters[filterName]) {
+                    continue;
+                }
+
+                const errorMessage = `Unknown filter '${filterName || filter}' for variable '${variableInfo.name}'`;
+                if (!seenFilterErrors.has(errorMessage)) {
+                    errors.push(errorMessage);
+                    seenFilterErrors.add(errorMessage);
+                }
+            }
+        }
+
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+
     prepare(variables) {
         if (!variables || typeof variables !== 'object') {
             throw new Error('Variables must be provided as an object');
@@ -76,12 +105,15 @@ class GeneralTemplate {
             varData = Object.assign({}, varData);
 
             if (parsedExpression.filters && parsedExpression.filters.length > 0) {
-                for (const filterName of parsedExpression.filters) {
-                    if (!TemplateFilters[filterName]) {
-                        throw new Error(`Unknown filter '${filterName}'`);
+                for (const filter of parsedExpression.filters) {
+                    const filterName = typeof filter === 'string' ? filter : filter?.name;
+                    const filterArgs = typeof filter === 'string' ? [] : (Array.isArray(filter?.args) ? filter.args : []);
+
+                    if (!filterName || !TemplateFilters[filterName]) {
+                        throw new Error(`Unknown filter '${filterName || filter}'`);
                     }
 
-                    TemplateFilters[filterName](varData);
+                    TemplateFilters[filterName](varData, ...filterArgs);
                 }
             }
 
@@ -101,10 +133,58 @@ class GeneralTemplate {
 
         return {
             name: segments[0],
-            filters: segments.slice(1)
+            filters: segments.slice(1).map(segment => this._parseFilter(segment))
+        };
+    }
+
+    _parseFilter(segment) {
+        const match = segment.match(FILTER_PATTERN);
+        if (!match) {
+            return {
+                name: segment,
+                args: []
+            };
+        }
+
+        const [, name, rawArgs] = match;
+        return {
+            name,
+            args: this._parseFilterArgs(rawArgs)
         };
     }
 
+    _parseFilterArgs(rawArgs) {
+        if (!rawArgs || !rawArgs.trim()) {
+            return [];
+        }
+
+        return rawArgs.split(',').map(arg => this._parseFilterArgValue(arg.trim()));
+    }
+
+    _parseFilterArgValue(rawArg) {
+        if ((rawArg.startsWith('"') && rawArg.endsWith('"')) || (rawArg.startsWith("'") && rawArg.endsWith("'"))) {
+            return rawArg.slice(1, -1);
+        }
+
+        if (rawArg === 'true') {
+            return true;
+        }
+
+        if (rawArg === 'false') {
+            return false;
+        }
+
+        if (rawArg === 'null') {
+            return null;
+        }
+
+        if (rawArg !== '' && !Number.isNaN(Number(rawArg))) {
+            return Number(rawArg);
+        }
+
+        return rawArg;
+    }
+
     _serializeVariable(varData) {
         if (varData.value === null || varData.value === undefined) {
             return '';