@safeaccess/inline 0.1.1 → 0.1.3

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

@@ -0,0 +1,283 @@
+import { InvalidFormatException } from '../exceptions/invalid-format-exception.js';
+import { SegmentType } 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 class SegmentParser {
+    segmentFilterParser;
+    /**
+     * Create a segment parser with a filter evaluator.
+     *
+     * @param segmentFilterParser - Delegate for [?filter] parsing.
+     */
+    constructor(segmentFilterParser) {
+        this.segmentFilterParser = segmentFilterParser;
+    }
+    /**
+     * 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) {
+        const segments = [];
+        const len = path.length;
+        const pos = { i: 0 };
+        if (path[0] === '$') {
+            pos.i = 1;
+            if (path[pos.i] === '.') {
+                pos.i++;
+            }
+        }
+        while (pos.i < len) {
+            if (path[pos.i] === '.') {
+                if (path[pos.i + 1] === '.') {
+                    pos.i += 2;
+                    segments.push(this.parseDescent(path, pos, len));
+                    continue;
+                }
+                pos.i++;
+                const segment = this.parseProjection(path, pos, len);
+                if (segment !== null) {
+                    segments.push(segment);
+                }
+                continue;
+            }
+            if (path[pos.i] === '[' && path[pos.i + 1] === '?') {
+                segments.push(this.parseFilter(path, pos, len));
+                continue;
+            }
+            if (path[pos.i] === '[') {
+                segments.push(this.parseBracket(path, pos, len));
+                continue;
+            }
+            if (path[pos.i] === '*') {
+                segments.push({ type: SegmentType.Wildcard });
+                pos.i++;
+                continue;
+            }
+            segments.push(this.parseKey(path, pos, len));
+        }
+        return segments;
+    }
+    /**
+     * 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.
+     */
+    parseDescent(path, pos, len) {
+        if (path[pos.i] === '[') {
+            let j = pos.i + 1;
+            while (j < len && path[j] !== ']') {
+                j++;
+            }
+            const inner = path.substring(pos.i + 1, j);
+            pos.i = j + 1;
+            if (inner.includes(',') && this.allQuoted(inner.split(','))) {
+                const parts = inner.split(',').map((p) => p.trim());
+                const keys = parts.map((p) => p.substring(1, p.length - 1));
+                return { type: SegmentType.DescentMulti, keys };
+            }
+            const quotedMatch = inner.match(/^(['"])(.*?)\1$/);
+            if (quotedMatch) {
+                return { type: SegmentType.Descent, key: quotedMatch[2] };
+            }
+            return { type: SegmentType.Descent, key: inner };
+        }
+        let key = '';
+        while (pos.i < len && path[pos.i] !== '.' && path[pos.i] !== '[') {
+            if (path[pos.i] === '\\' && path[pos.i + 1] === '.') {
+                key += '.';
+                pos.i += 2;
+            }
+            else {
+                key += path[pos.i];
+                pos.i++;
+            }
+        }
+        return { type: SegmentType.Descent, key };
+    }
+    /**
+     * 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.
+     */
+    parseProjection(path, pos, len) {
+        if (path[pos.i] !== '{') {
+            return null;
+        }
+        let j = pos.i + 1;
+        while (j < len && path[j] !== '}') {
+            j++;
+        }
+        const inner = path.substring(pos.i + 1, j);
+        pos.i = j + 1;
+        const fields = [];
+        for (const entry of inner
+            .split(',')
+            .map((e) => e.trim())
+            .filter((e) => e !== '')) {
+            const colonIdx = entry.indexOf(':');
+            if (colonIdx !== -1) {
+                fields.push({
+                    alias: entry.substring(0, colonIdx).trim(),
+                    source: entry.substring(colonIdx + 1).trim(),
+                });
+            }
+            else {
+                fields.push({ alias: entry, source: entry });
+            }
+        }
+        return { type: SegmentType.Projection, fields };
+    }
+    /**
+     * 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.
+     */
+    parseFilter(path, pos, len) {
+        let depth = 1;
+        let j = pos.i + 1;
+        while (j < len && depth > 0) {
+            j++;
+            if (path[j] === '[') {
+                depth++;
+            }
+            if (path[j] === ']') {
+                depth--;
+            }
+        }
+        const filterExpr = path.substring(pos.i + 2, j);
+        pos.i = j + 1;
+        return { type: SegmentType.Filter, expression: this.segmentFilterParser.parse(filterExpr) };
+    }
+    /**
+     * 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.
+     */
+    parseBracket(path, pos, len) {
+        let j = pos.i + 1;
+        while (j < len && path[j] !== ']') {
+            j++;
+        }
+        const inner = path.substring(pos.i + 1, j);
+        pos.i = j + 1;
+        if (inner.includes(',')) {
+            const parts = inner.split(',').map((p) => p.trim());
+            if (this.allQuoted(parts)) {
+                const keys = parts.map((p) => p.substring(1, p.length - 1));
+                return { type: SegmentType.MultiKey, keys };
+            }
+            let allNumeric = true;
+            for (const p of parts) {
+                if (isNaN(Number(p.trim())) || p.trim() === '') {
+                    allNumeric = false;
+                    break;
+                }
+            }
+            if (allNumeric) {
+                return { type: SegmentType.MultiIndex, indices: parts.map((p) => parseInt(p, 10)) };
+            }
+        }
+        const quotedMatch = inner.match(/^(['"])(.*?)\1$/);
+        if (quotedMatch) {
+            return { type: SegmentType.Key, value: quotedMatch[2] };
+        }
+        if (inner.includes(':')) {
+            const sliceParts = inner.split(':');
+            const start = sliceParts[0] !== '' ? parseInt(sliceParts[0], 10) : null;
+            const end = sliceParts.length > 1 && sliceParts[1] !== '' ? parseInt(sliceParts[1], 10) : null;
+            const rawStep = sliceParts.length > 2 && sliceParts[2] !== '' ? parseInt(sliceParts[2], 10) : null;
+            if (rawStep === 0) {
+                throw new InvalidFormatException('Slice step cannot be zero.');
+            }
+            return { type: SegmentType.Slice, start, end, step: rawStep };
+        }
+        if (inner === '*') {
+            return { type: SegmentType.Wildcard };
+        }
+        return { type: SegmentType.Key, value: inner };
+    }
+    /**
+     * 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.
+     */
+    parseKey(path, pos, len) {
+        let key = '';
+        while (pos.i < len && path[pos.i] !== '.' && path[pos.i] !== '[') {
+            if (path[pos.i] === '\\' && path[pos.i + 1] === '.') {
+                key += '.';
+                pos.i += 2;
+            }
+            else {
+                key += path[pos.i];
+                pos.i++;
+            }
+        }
+        return { type: SegmentType.Key, value: key };
+    }
+    /**
+     * 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.
+     */
+    allQuoted(parts) {
+        for (const raw of parts) {
+            const p = raw.trim();
+            if (!(p.startsWith("'") && p.endsWith("'")) &&
+                !(p.startsWith('"') && p.endsWith('"'))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * 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) {
+        let normalized = path.replace(/\[([^\]]+)\]/g, '.$1');
+        const placeholder = '\x00ESC_DOT\x00';
+        normalized = normalized.replace(/\\\./g, placeholder);
+        const keys = normalized.split('.');
+        return keys.map((k) => k.replace(new RegExp(placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '.'));
+    }
+}

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

@@ -0,0 +1,149 @@
+import type { FilterEvaluatorInterface } from '../contracts/filter-evaluator-interface.js';
+import type { Segment } from './segment-type.js';
+/**
+ * Resolve typed path segments against nested data structures.
+ *
+ * Traverses data using segment arrays produced by {@link SegmentParser},
+ * dispatching to segment-type-specific handlers for key, wildcard,
+ * descent, filter, slice, multi-key/index, and projection operations.
+ *
+ * @internal
+ *
+ * @see SegmentParser           Produces the segment arrays this resolver consumes.
+ * @see SegmentType             Enum governing which handler is dispatched.
+ * @see FilterEvaluatorInterface  Delegate for filter predicate evaluation.
+ * @see DotNotationParser       Invokes this resolver for path queries.
+ */
+export declare class SegmentPathResolver {
+    private readonly segmentFilterParser;
+    /**
+     * Create a resolver with a filter evaluator.
+     *
+     * @param segmentFilterParser - Delegate for filter evaluation.
+     */
+    constructor(segmentFilterParser: FilterEvaluatorInterface);
+    /**
+     * Resolve a value by walking segments starting at the given index.
+     *
+     * @param current - Current data node.
+     * @param segments - Typed segment array from {@link SegmentParser}.
+     * @param index - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     */
+    resolve(current: unknown, segments: ReadonlyArray<Segment>, index: number, defaultValue: unknown, maxDepth: number): unknown;
+    /**
+     * Resolve a simple key/index segment.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     */
+    private segmentAny;
+    /**
+     * Resolve a recursive descent segment for a single key.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching the descent key.
+     */
+    private segmentDescent;
+    /**
+     * Resolve a recursive descent segment for multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching any of the descent keys.
+     */
+    private segmentDescentMulti;
+    /**
+     * Resolve a wildcard segment, expanding all children.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for all children.
+     */
+    private segmentWildcard;
+    /**
+     * Resolve a filter segment, applying predicates to array items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of items passing the filter predicate.
+     */
+    private segmentFilter;
+    /**
+     * Resolve a multi-key segment, selecting values by multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each key.
+     */
+    private segmentMultiKey;
+    /**
+     * Resolve a multi-index segment, selecting values by multiple indices.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each index.
+     */
+    private segmentMultiIndex;
+    /**
+     * Resolve a slice segment on an array (start:end:step).
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values matching the slice range.
+     */
+    private segmentSlice;
+    /**
+     * Resolve a projection segment, selecting specific fields from items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Projected item(s) with only the specified fields.
+     */
+    private segmentProjection;
+    /**
+     * Recursively collect values matching a descent key from nested data.
+     *
+     * @param current - Current data node.
+     * @param key - Key to search for recursively.
+     * @param segments - Typed segment array.
+     * @param nextIndex - Next segment index after the descent.
+     * @param defaultValue - Fallback value.
+     * @param results - Collector array (mutated in place).
+     * @param maxDepth - Maximum recursion depth.
+     */
+    private collectDescent;
+}