@safeaccess/inline 0.1.1 → 0.1.3

package/dist/path-query/segment-filter-parser.d.ts

@@ -0,0 +1,142 @@
+import type { FilterEvaluatorInterface } from '../contracts/filter-evaluator-interface.js';
+import type { SecurityGuardInterface } from '../contracts/security-guard-interface.js';
+import type { FilterExpression } from './segment-type.js';
+/**
+ * Parse and evaluate filter predicate expressions for path queries.
+ *
+ * Handles `[?expression]` syntax with comparison operators (==, !=, >, <, >=, <=),
+ * logical operators (&& and ||), and built-in functions (starts_with, contains, values).
+ * Supports arithmetic expressions and nested field access via dot-notation.
+ *
+ * @internal
+ *
+ * @see FilterEvaluatorInterface  Contract this class implements.
+ * @see SegmentParser             Uses this for filter segment parsing.
+ * @see SegmentPathResolver       Uses this for filter evaluation during resolution.
+ * @see SecurityGuardInterface    Guards field access against forbidden keys.
+ */
+export declare class SegmentFilterParser implements FilterEvaluatorInterface {
+    private readonly guard;
+    /**
+     * Create a filter parser with security guard for field validation.
+     *
+     * @param guard - Key validator for field access.
+     */
+    constructor(guard: SecurityGuardInterface);
+    /**
+     * Parse a filter expression into structured conditions and logical operators.
+     *
+     * @param expression - Raw filter string (e.g. "age>18 && active==true").
+     * @returns Parsed structure with conditions and logical operators.
+     *
+     * @throws {InvalidFormatException} When the expression syntax is invalid.
+     */
+    parse(expression: string): FilterExpression;
+    /**
+     * Evaluate a parsed filter expression against a data item.
+     *
+     * @param item - Data item to test.
+     * @param expr - Parsed expression.
+     * @returns True if the item satisfies all conditions.
+     */
+    evaluate(item: Record<string, unknown>, expr: FilterExpression): boolean;
+    /**
+     * Split expression by logical operators (&& and ||), respecting quotes.
+     *
+     * @param expression - Raw expression string.
+     * @returns Tokens and their joining operators.
+     */
+    private splitLogical;
+    /**
+     * Parse a single condition token into a structured object.
+     *
+     * @param token - Single condition (e.g. "age>18", "starts_with(@.name, 'J')").
+     * @returns Parsed condition.
+     *
+     * @throws {InvalidFormatException} When the condition syntax is invalid.
+     */
+    private parseCondition;
+    /**
+     * Parse a raw value string to its native type.
+     *
+     * @param raw - Raw value (e.g. "true", "'hello'", "42").
+     * @returns Native value.
+     */
+    private parseValue;
+    /**
+     * Parse a non-keyword raw value to number or string.
+     *
+     * @param raw - Raw value string.
+     * @returns Typed value.
+     */
+    private parseValueDefault;
+    /**
+     * Evaluate a single parsed condition against a data item.
+     *
+     * @param item - Data item.
+     * @param condition - Parsed condition.
+     * @returns True if the condition is satisfied.
+     */
+    private evaluateCondition;
+    /**
+     * Dispatch and evaluate a built-in filter function.
+     *
+     * @param item - Data item.
+     * @param func - Function name.
+     * @param funcArgs - Function arguments.
+     * @returns Function result.
+     *
+     * @throws {InvalidFormatException} When the function name is unknown.
+     */
+    private evaluateFunction;
+    /**
+     * Evaluate the starts_with() filter function.
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field, prefix].
+     * @returns True if the field value starts with the prefix.
+     */
+    private evalStartsWith;
+    /**
+     * Evaluate the contains() filter function.
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field, needle].
+     * @returns True if the field value contains the needle.
+     */
+    private evalContains;
+    /**
+     * Evaluate the values() filter function (returns count).
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field].
+     * @returns Number of elements in the field array, or 0.
+     */
+    private evalValues;
+    /**
+     * Resolve an arithmetic expression from a filter predicate.
+     *
+     * @param item - Data item for field resolution.
+     * @param expr - Arithmetic expression (e.g. "@.price * @.qty").
+     * @returns Computed result, or null on failure.
+     */
+    private resolveArithmetic;
+    /**
+     * Resolve a filter argument to its value from the data item.
+     *
+     * @param item - Data item.
+     * @param arg - Argument ("@", "@.field", or "field").
+     * @returns Resolved value.
+     */
+    private resolveFilterArg;
+    /**
+     * Resolve a dot-separated field path from a data item.
+     *
+     * @param item - Data item.
+     * @param field - Dot-separated field path.
+     * @returns Resolved value, or null if not found.
+     *
+     * @throws {SecurityException} When a field key is forbidden.
+     */
+    private resolveField;
+}

package/dist/path-query/segment-filter-parser.js

@@ -0,0 +1,384 @@
+import { InvalidFormatException } from '../exceptions/invalid-format-exception.js';
+/**
+ * Parse and evaluate filter predicate expressions for path queries.
+ *
+ * Handles `[?expression]` syntax with comparison operators (==, !=, >, <, >=, <=),
+ * logical operators (&& and ||), and built-in functions (starts_with, contains, values).
+ * Supports arithmetic expressions and nested field access via dot-notation.
+ *
+ * @internal
+ *
+ * @see FilterEvaluatorInterface  Contract this class implements.
+ * @see SegmentParser             Uses this for filter segment parsing.
+ * @see SegmentPathResolver       Uses this for filter evaluation during resolution.
+ * @see SecurityGuardInterface    Guards field access against forbidden keys.
+ */
+export class SegmentFilterParser {
+    guard;
+    /**
+     * Create a filter parser with security guard for field validation.
+     *
+     * @param guard - Key validator for field access.
+     */
+    constructor(guard) {
+        this.guard = guard;
+    }
+    /**
+     * Parse a filter expression into structured conditions and logical operators.
+     *
+     * @param expression - Raw filter string (e.g. "age>18 && active==true").
+     * @returns Parsed structure with conditions and logical operators.
+     *
+     * @throws {InvalidFormatException} When the expression syntax is invalid.
+     */
+    parse(expression) {
+        const conditions = [];
+        const parts = this.splitLogical(expression);
+        for (const token of parts.tokens) {
+            conditions.push(this.parseCondition(token.trim()));
+        }
+        return { conditions, logicals: parts.operators };
+    }
+    /**
+     * Evaluate a parsed filter expression against a data item.
+     *
+     * @param item - Data item to test.
+     * @param expr - Parsed expression.
+     * @returns True if the item satisfies all conditions.
+     */
+    evaluate(item, expr) {
+        if (expr.conditions.length === 0) {
+            return false;
+        }
+        let result = this.evaluateCondition(item, expr.conditions[0]);
+        for (let i = 0; i < expr.logicals.length; i++) {
+            const nextResult = this.evaluateCondition(item, expr.conditions[i + 1]);
+            if (expr.logicals[i] === '&&') {
+                result = result && nextResult;
+            }
+            else {
+                result = result || nextResult;
+            }
+        }
+        return result;
+    }
+    /**
+     * Split expression by logical operators (&& and ||), respecting quotes.
+     *
+     * @param expression - Raw expression string.
+     * @returns Tokens and their joining operators.
+     */
+    splitLogical(expression) {
+        const tokens = [];
+        const operators = [];
+        let current = '';
+        let inString = false;
+        let stringChar = '';
+        for (let i = 0; i < expression.length; i++) {
+            const ch = expression[i];
+            if (inString) {
+                current += ch;
+                if (ch === stringChar) {
+                    inString = false;
+                }
+                continue;
+            }
+            if (ch === "'" || ch === '"') {
+                inString = true;
+                stringChar = ch;
+                current += ch;
+                continue;
+            }
+            if (ch === '&' && expression[i + 1] === '&') {
+                tokens.push(current);
+                operators.push('&&');
+                current = '';
+                i++;
+                continue;
+            }
+            if (ch === '|' && expression[i + 1] === '|') {
+                tokens.push(current);
+                operators.push('||');
+                current = '';
+                i++;
+                continue;
+            }
+            current += ch;
+        }
+        tokens.push(current);
+        return { tokens, operators };
+    }
+    /**
+     * Parse a single condition token into a structured object.
+     *
+     * @param token - Single condition (e.g. "age>18", "starts_with(@.name, 'J')").
+     * @returns Parsed condition.
+     *
+     * @throws {InvalidFormatException} When the condition syntax is invalid.
+     */
+    parseCondition(token) {
+        const operators = ['>=', '<=', '!=', '==', '>', '<'];
+        const funcCompareMatch = token.match(/^(\w+)\(([^)]*)\)\s*(>=|<=|!=|==|>|<)\s*(.+)$/);
+        if (funcCompareMatch) {
+            const func = funcCompareMatch[1];
+            const argsRaw = funcCompareMatch[2];
+            const operator = funcCompareMatch[3];
+            const rawValue = funcCompareMatch[4].trim();
+            const funcArgs = argsRaw.split(',').map((a) => a.trim());
+            return {
+                field: funcArgs[0],
+                operator,
+                value: this.parseValue(rawValue),
+                func,
+                funcArgs,
+            };
+        }
+        const funcBoolMatch = token.match(/^(\w+)\(([^)]*)\)$/);
+        if (funcBoolMatch) {
+            const func = funcBoolMatch[1];
+            const argsRaw = funcBoolMatch[2];
+            const funcArgs = argsRaw.split(',').map((a) => a.trim());
+            return {
+                field: funcArgs[0],
+                operator: '==',
+                value: true,
+                func,
+                funcArgs,
+            };
+        }
+        for (const op of operators) {
+            const pos = token.indexOf(op);
+            if (pos !== -1) {
+                const field = token.substring(0, pos).trim();
+                const rawValue = token.substring(pos + op.length).trim();
+                return {
+                    field,
+                    operator: op,
+                    value: this.parseValue(rawValue),
+                };
+            }
+        }
+        throw new InvalidFormatException(`Invalid filter condition: "${token}"`);
+    }
+    /**
+     * Parse a raw value string to its native type.
+     *
+     * @param raw - Raw value (e.g. "true", "'hello'", "42").
+     * @returns Native value.
+     */
+    parseValue(raw) {
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        if (raw === 'null')
+            return null;
+        return this.parseValueDefault(raw);
+    }
+    /**
+     * Parse a non-keyword raw value to number or string.
+     *
+     * @param raw - Raw value string.
+     * @returns Typed value.
+     */
+    parseValueDefault(raw) {
+        if ((raw.startsWith("'") && raw.endsWith("'")) ||
+            (raw.startsWith('"') && raw.endsWith('"'))) {
+            return raw.substring(1, raw.length - 1);
+        }
+        if (!isNaN(Number(raw)) && raw !== '') {
+            return raw.includes('.') ? parseFloat(raw) : parseInt(raw, 10);
+        }
+        return raw;
+    }
+    /**
+     * Evaluate a single parsed condition against a data item.
+     *
+     * @param item - Data item.
+     * @param condition - Parsed condition.
+     * @returns True if the condition is satisfied.
+     */
+    evaluateCondition(item, condition) {
+        let fieldValue;
+        if (condition.func !== undefined) {
+            fieldValue = this.evaluateFunction(item, condition.func, condition.funcArgs ?? []);
+        }
+        else if (/[@\w.]+\s*[+\-*/]\s*[@\w.]+/.test(condition.field)) {
+            fieldValue = this.resolveArithmetic(item, condition.field);
+        }
+        else {
+            fieldValue = this.resolveField(item, condition.field);
+        }
+        const expected = condition.value;
+        switch (condition.operator) {
+            case '==':
+                return fieldValue === expected;
+            case '!=':
+                return fieldValue !== expected;
+            case '>':
+                return fieldValue > expected;
+            case '<':
+                return fieldValue < expected;
+            case '>=':
+                return fieldValue >= expected;
+            case '<=':
+                return fieldValue <= expected;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Dispatch and evaluate a built-in filter function.
+     *
+     * @param item - Data item.
+     * @param func - Function name.
+     * @param funcArgs - Function arguments.
+     * @returns Function result.
+     *
+     * @throws {InvalidFormatException} When the function name is unknown.
+     */
+    evaluateFunction(item, func, funcArgs) {
+        switch (func) {
+            case 'starts_with':
+                return this.evalStartsWith(item, funcArgs);
+            case 'contains':
+                return this.evalContains(item, funcArgs);
+            case 'values':
+                return this.evalValues(item, funcArgs);
+            default:
+                throw new InvalidFormatException(`Unknown filter function: "${func}"`);
+        }
+    }
+    /**
+     * Evaluate the starts_with() filter function.
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field, prefix].
+     * @returns True if the field value starts with the prefix.
+     */
+    evalStartsWith(item, funcArgs) {
+        const val = this.resolveFilterArg(item, funcArgs[0] ?? '@');
+        if (typeof val !== 'string') {
+            return false;
+        }
+        const prefix = String(this.parseValue((funcArgs[1] ?? '').trim()));
+        return val.startsWith(prefix);
+    }
+    /**
+     * Evaluate the contains() filter function.
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field, needle].
+     * @returns True if the field value contains the needle.
+     */
+    evalContains(item, funcArgs) {
+        const val = this.resolveFilterArg(item, funcArgs[0] ?? '@');
+        const needle = String(this.parseValue((funcArgs[1] ?? '').trim()));
+        if (typeof val === 'string') {
+            return val.includes(needle);
+        }
+        if (Array.isArray(val)) {
+            return val.includes(needle);
+        }
+        return false;
+    }
+    /**
+     * Evaluate the values() filter function (returns count).
+     *
+     * @param item - Data item.
+     * @param funcArgs - [field].
+     * @returns Number of elements in the field array, or 0.
+     */
+    evalValues(item, funcArgs) {
+        const val = this.resolveFilterArg(item, funcArgs[0] ?? '@');
+        if (Array.isArray(val)) {
+            return val.length;
+        }
+        return 0;
+    }
+    /**
+     * Resolve an arithmetic expression from a filter predicate.
+     *
+     * @param item - Data item for field resolution.
+     * @param expr - Arithmetic expression (e.g. "@.price * @.qty").
+     * @returns Computed result, or null on failure.
+     */
+    resolveArithmetic(item, expr) {
+        const m = expr.match(/^([@\w.]+)\s*([+\-*/])\s*([@\w.]+|\d+(?:\.\d+)?)$/);
+        if (!m) {
+            return null;
+        }
+        const toNumber = (token) => {
+            if (!token.startsWith('@') && !isNaN(Number(token)) && token !== '') {
+                return token.includes('.') ? parseFloat(token) : parseInt(token, 10);
+            }
+            const val = this.resolveFilterArg(item, token);
+            if (typeof val === 'number') {
+                return val;
+            }
+            if (typeof val === 'string' && !isNaN(Number(val)) && val !== '') {
+                return val.includes('.') ? parseFloat(val) : parseInt(val, 10);
+            }
+            return null;
+        };
+        const left = toNumber(m[1]);
+        const right = toNumber(m[3]);
+        if (left === null || right === null) {
+            return null;
+        }
+        switch (m[2]) {
+            case '+':
+                return left + right;
+            case '-':
+                return left - right;
+            case '*':
+                return left * right;
+            default:
+                return right !== 0 ? left / right : null;
+        }
+    }
+    /**
+     * Resolve a filter argument to its value from the data item.
+     *
+     * @param item - Data item.
+     * @param arg - Argument ("@", "@.field", or "field").
+     * @returns Resolved value.
+     */
+    resolveFilterArg(item, arg) {
+        if (arg === '' || arg === '@') {
+            return item;
+        }
+        if (arg.startsWith('@.')) {
+            return this.resolveField(item, arg.substring(2));
+        }
+        return this.resolveField(item, arg);
+    }
+    /**
+     * Resolve a dot-separated field path from a data item.
+     *
+     * @param item - Data item.
+     * @param field - Dot-separated field path.
+     * @returns Resolved value, or null if not found.
+     *
+     * @throws {SecurityException} When a field key is forbidden.
+     */
+    resolveField(item, field) {
+        if (field.includes('.')) {
+            let current = item;
+            for (const key of field.split('.')) {
+                this.guard.assertSafeKey(key);
+                if (typeof current === 'object' &&
+                    current !== null &&
+                    Object.prototype.hasOwnProperty.call(current, key)) {
+                    current = current[key];
+                }
+                else {
+                    return null;
+                }
+            }
+            return current;
+        }
+        this.guard.assertSafeKey(field);
+        return item[field] ?? null;
+    }
+}

package/dist/path-query/segment-parser.d.ts

@@ -0,0 +1,98 @@
+import type { FilterEvaluatorInterface } from '../contracts/filter-evaluator-interface.js';
+import type { Segment } from './segment-type.js';
+/**
+ * Parse dot-notation path strings into typed segment arrays.
+ *
+ * Converts path expressions (e.g. "users[0].address..city") into ordered
+ * segment arrays with {@link SegmentType} metadata for resolution by
+ * {@link SegmentPathResolver}. Supports key, index, wildcard, descent,
+ * multi-key/index, filter, slice, and projection segment types.
+ *
+ * @internal
+ *
+ * @see SegmentType          Enum of all segment types produced.
+ * @see SegmentPathResolver  Consumer that resolves segments against data.
+ * @see FilterEvaluatorInterface  Delegate for filter expression parsing.
+ */
+export declare class SegmentParser {
+    private readonly segmentFilterParser;
+    /**
+     * Create a segment parser with a filter evaluator.
+     *
+     * @param segmentFilterParser - Delegate for [?filter] parsing.
+     */
+    constructor(segmentFilterParser: FilterEvaluatorInterface);
+    /**
+     * Parse a dot-notation path into an ordered array of typed segments.
+     *
+     * @param path - Dot-notation path expression.
+     * @returns Typed segment array.
+     *
+     * @throws {InvalidFormatException} When slice step is zero.
+     */
+    parseSegments(path: string): Segment[];
+    /**
+     * Parse a recursive descent segment (`..key` or `..[...]`).
+     *
+     * @param path - Full path string.
+     * @param pos - Current position (mutated in place).
+     * @param len - Total path length.
+     * @returns Parsed descent segment.
+     */
+    private parseDescent;
+    /**
+     * Parse a projection segment (`.{field1, field2}` or `.{alias: field}`).
+     *
+     * @param path - Full path string.
+     * @param pos - Current position (mutated in place).
+     * @param len - Total path length.
+     * @returns Parsed projection segment, or null if not a projection.
+     */
+    private parseProjection;
+    /**
+     * Parse a filter segment (`[?expression]`).
+     *
+     * @param path - Full path string.
+     * @param pos - Current position (mutated in place).
+     * @param len - Total path length.
+     * @returns Parsed filter segment.
+     */
+    private parseFilter;
+    /**
+     * Parse a bracket segment (`[0]`, `[0,1,2]`, `[0:5]`, `['key']`, `[*]`).
+     *
+     * @param path - Full path string.
+     * @param pos - Current position (mutated in place).
+     * @param len - Total path length.
+     * @returns Parsed bracket segment.
+     *
+     * @throws {InvalidFormatException} When slice step is zero.
+     */
+    private parseBracket;
+    /**
+     * Parse a regular dot-separated key with escaped-dot support.
+     *
+     * @param path - Full path string.
+     * @param pos - Current position (mutated in place).
+     * @param len - Total path length.
+     * @returns Parsed key segment.
+     */
+    private parseKey;
+    /**
+     * Check if all parts in a comma-separated list are quoted strings.
+     *
+     * @param parts - Raw parts from split.
+     * @returns True if every part is single- or double-quoted.
+     */
+    private allQuoted;
+    /**
+     * Parse a simple dot-notation path into plain string keys.
+     *
+     * Handles bracket notation and escaped dots. Does not produce typed
+     * segments - used for set/remove operations via {@link DotNotationParser}.
+     *
+     * @param path - Simple dot-notation path.
+     * @returns Ordered list of key strings.
+     */
+    parseKeys(path: string): string[];
+}