@a2ui-sdk/utils 0.0.0

package/dist/0.9/interpolation/lexer.test.js

@@ -0,0 +1,360 @@
+/**
+ * Tests for the lexer (tokenizer).
+ */
+import { describe, it, expect } from 'vitest';
+import { tokenize } from './lexer.js';
+import { TokenType } from './types.js';
+describe('Lexer', () => {
+    describe('TEXT tokens', () => {
+        it('should tokenize plain text', () => {
+            const tokens = tokenize('Hello World');
+            expect(tokens).toHaveLength(2); // TEXT + EOF
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'Hello World',
+                start: 0,
+                end: 11,
+            });
+        });
+        it('should return only EOF for empty string', () => {
+            const tokens = tokenize('');
+            expect(tokens).toHaveLength(1);
+            expect(tokens[0].type).toBe(TokenType.EOF);
+        });
+        it('should handle text with special characters', () => {
+            const tokens = tokenize('Hello @world! #123');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'Hello @world! #123',
+            });
+        });
+        it('should handle multi-line text', () => {
+            const tokens = tokenize('Line 1\nLine 2');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'Line 1\nLine 2',
+            });
+        });
+    });
+    describe('EXPR_START and EXPR_END tokens', () => {
+        it('should tokenize expression delimiters', () => {
+            const tokens = tokenize('${/path}');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.EXPR_START,
+                value: '${',
+            });
+            expect(tokens[1]).toMatchObject({ type: TokenType.PATH, value: '/path' });
+            expect(tokens[2]).toMatchObject({ type: TokenType.EXPR_END, value: '}' });
+        });
+        it('should handle multiple expressions', () => {
+            const tokens = tokenize('${/a} ${/b}');
+            const types = tokens.map((t) => t.type);
+            expect(types).toEqual([
+                TokenType.EXPR_START,
+                TokenType.PATH,
+                TokenType.EXPR_END,
+                TokenType.TEXT,
+                TokenType.EXPR_START,
+                TokenType.PATH,
+                TokenType.EXPR_END,
+                TokenType.EOF,
+            ]);
+        });
+        it('should handle expression at start of string', () => {
+            const tokens = tokenize('${/name} is here');
+            expect(tokens[0].type).toBe(TokenType.EXPR_START);
+        });
+        it('should handle expression at end of string', () => {
+            const tokens = tokenize('Name: ${/name}');
+            expect(tokens[tokens.length - 2].type).toBe(TokenType.EXPR_END);
+        });
+    });
+    describe('PATH tokens', () => {
+        it('should tokenize absolute paths', () => {
+            const tokens = tokenize('${/user/name}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/user/name',
+            });
+        });
+        it('should tokenize root path', () => {
+            const tokens = tokenize('${/}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/',
+            });
+        });
+        it('should tokenize paths with array indices', () => {
+            const tokens = tokenize('${/items/0}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/items/0',
+            });
+        });
+        it('should tokenize relative paths', () => {
+            const tokens = tokenize('${name}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: 'name',
+            });
+        });
+        it('should tokenize nested relative paths', () => {
+            const tokens = tokenize('${profile/name}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: 'profile/name',
+            });
+        });
+        it('should tokenize paths with hyphens', () => {
+            const tokens = tokenize('${/user-data/first-name}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/user-data/first-name',
+            });
+        });
+        it('should tokenize paths with underscores', () => {
+            const tokens = tokenize('${/user_data/first_name}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/user_data/first_name',
+            });
+        });
+    });
+    describe('IDENTIFIER, LPAREN, RPAREN, COMMA tokens', () => {
+        it('should tokenize no-argument function call', () => {
+            const tokens = tokenize('${now()}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.IDENTIFIER,
+                value: 'now',
+            });
+            expect(tokens[2]).toMatchObject({ type: TokenType.LPAREN, value: '(' });
+            expect(tokens[3]).toMatchObject({ type: TokenType.RPAREN, value: ')' });
+        });
+        it('should tokenize function with single argument', () => {
+            const tokens = tokenize("${upper('hello')}");
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.IDENTIFIER,
+                value: 'upper',
+            });
+            expect(tokens[2]).toMatchObject({ type: TokenType.LPAREN, value: '(' });
+            expect(tokens[3]).toMatchObject({
+                type: TokenType.STRING,
+                value: 'hello',
+            });
+            expect(tokens[4]).toMatchObject({ type: TokenType.RPAREN, value: ')' });
+        });
+        it('should tokenize function with multiple arguments', () => {
+            const tokens = tokenize('${add(1, 2, 3)}');
+            const types = tokens.map((t) => t.type);
+            expect(types).toContain(TokenType.COMMA);
+            // Count commas
+            const commaCount = tokens.filter((t) => t.type === TokenType.COMMA).length;
+            expect(commaCount).toBe(2);
+        });
+        it('should handle whitespace around function parts', () => {
+            const tokens = tokenize('${ upper ( 1 , 2 ) }');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.IDENTIFIER,
+                value: 'upper',
+            });
+            expect(tokens[2]).toMatchObject({ type: TokenType.LPAREN });
+            expect(tokens[3]).toMatchObject({ type: TokenType.NUMBER, value: '1' });
+            expect(tokens[4]).toMatchObject({ type: TokenType.COMMA });
+            expect(tokens[5]).toMatchObject({ type: TokenType.NUMBER, value: '2' });
+            expect(tokens[6]).toMatchObject({ type: TokenType.RPAREN });
+        });
+        it('should tokenize function names with underscores', () => {
+            const tokens = tokenize('${format_date()}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.IDENTIFIER,
+                value: 'format_date',
+            });
+        });
+    });
+    describe('STRING, NUMBER, BOOLEAN literal tokens', () => {
+        it('should tokenize string literals', () => {
+            const tokens = tokenize("${'hello'}");
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.STRING,
+                value: 'hello',
+            });
+        });
+        it('should tokenize string with spaces', () => {
+            const tokens = tokenize("${'hello world'}");
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.STRING,
+                value: 'hello world',
+            });
+        });
+        it('should handle escaped quotes in strings', () => {
+            const tokens = tokenize("${'it\\'s here'}");
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.STRING,
+                value: "it's here",
+            });
+        });
+        it('should tokenize integer numbers', () => {
+            const tokens = tokenize('${42}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.NUMBER,
+                value: '42',
+            });
+        });
+        it('should tokenize negative numbers', () => {
+            const tokens = tokenize('${-5}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.NUMBER,
+                value: '-5',
+            });
+        });
+        it('should tokenize decimal numbers', () => {
+            const tokens = tokenize('${3.14}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.NUMBER,
+                value: '3.14',
+            });
+        });
+        it('should tokenize negative decimal numbers', () => {
+            const tokens = tokenize('${-3.14}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.NUMBER,
+                value: '-3.14',
+            });
+        });
+        it('should tokenize boolean true', () => {
+            const tokens = tokenize('${true}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.BOOLEAN,
+                value: 'true',
+            });
+        });
+        it('should tokenize boolean false', () => {
+            const tokens = tokenize('${false}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.BOOLEAN,
+                value: 'false',
+            });
+        });
+        it('should not tokenize partial boolean words', () => {
+            const tokens = tokenize('${trueValue}');
+            // Should be PATH, not BOOLEAN
+            expect(tokens[1].type).toBe(TokenType.PATH);
+            expect(tokens[1].value).toBe('trueValue');
+        });
+    });
+    describe('escape sequence handling', () => {
+        it('should convert \\${ to literal ${', () => {
+            const tokens = tokenize('\\${escaped}');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: '${escaped}',
+            });
+        });
+        it('should handle multiple escapes', () => {
+            const tokens = tokenize('\\${a} \\${b}');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: '${a} ${b}',
+            });
+        });
+        it('should handle mix of escaped and unescaped', () => {
+            const tokens = tokenize('\\${escaped} ${/real}');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: '${escaped} ',
+            });
+            expect(tokens[1]).toMatchObject({ type: TokenType.EXPR_START });
+            expect(tokens[2]).toMatchObject({ type: TokenType.PATH, value: '/real' });
+        });
+        it('should handle escape at end of string', () => {
+            const tokens = tokenize('text \\${end}');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'text ${end}',
+            });
+        });
+        it('should handle backslash not followed by ${', () => {
+            const tokens = tokenize('back\\slash');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'back\\slash',
+            });
+        });
+    });
+    describe('JSON Pointer escapes in PATH tokens', () => {
+        it('should preserve ~1 escape (forward slash) in path', () => {
+            const tokens = tokenize('${/a~1b}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/a~1b',
+            });
+        });
+        it('should preserve ~0 escape (tilde) in path', () => {
+            const tokens = tokenize('${/m~0n}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/m~0n',
+            });
+        });
+        it('should preserve multiple escapes in path', () => {
+            const tokens = tokenize('${/a~1b~0c}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/a~1b~0c',
+            });
+        });
+        it('should handle tilde without following 0 or 1', () => {
+            const tokens = tokenize('${/path~other}');
+            expect(tokens[1]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/path~other',
+            });
+        });
+    });
+    describe('nested expressions', () => {
+        it('should tokenize nested expression in function arg', () => {
+            const tokens = tokenize('${upper(${/name})}');
+            const types = tokens.map((t) => t.type);
+            expect(types).toEqual([
+                TokenType.EXPR_START, // ${
+                TokenType.IDENTIFIER, // upper
+                TokenType.LPAREN, // (
+                TokenType.EXPR_START, // ${
+                TokenType.PATH, // /name
+                TokenType.EXPR_END, // }
+                TokenType.RPAREN, // )
+                TokenType.EXPR_END, // }
+                TokenType.EOF,
+            ]);
+        });
+        it('should tokenize deeply nested expressions', () => {
+            const tokens = tokenize('${a(${b(${/c})})}');
+            // Count nested ${ tokens
+            const exprStartCount = tokens.filter((t) => t.type === TokenType.EXPR_START).length;
+            expect(exprStartCount).toBe(3);
+        });
+    });
+    describe('complex expressions', () => {
+        it('should tokenize text with expression in middle', () => {
+            const tokens = tokenize('Hello, ${/user/name}!');
+            expect(tokens[0]).toMatchObject({
+                type: TokenType.TEXT,
+                value: 'Hello, ',
+            });
+            expect(tokens[1]).toMatchObject({ type: TokenType.EXPR_START });
+            expect(tokens[2]).toMatchObject({
+                type: TokenType.PATH,
+                value: '/user/name',
+            });
+            expect(tokens[3]).toMatchObject({ type: TokenType.EXPR_END });
+            expect(tokens[4]).toMatchObject({ type: TokenType.TEXT, value: '!' });
+        });
+        it('should tokenize multiple expressions in text', () => {
+            const tokens = tokenize('${/a} + ${/b} = ${/c}');
+            const textTokens = tokens.filter((t) => t.type === TokenType.TEXT);
+            const pathTokens = tokens.filter((t) => t.type === TokenType.PATH);
+            expect(textTokens.length).toBe(2); // ' + ' and ' = '
+            expect(pathTokens.length).toBe(3);
+        });
+    });
+});

package/dist/0.9/interpolation/parser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parser for string interpolation expressions.
+ *
+ * Converts a sequence of tokens into an Abstract Syntax Tree (AST).
+ * Implements a recursive descent parser for the LL(1) grammar.
+ */
+import type { Token, InterpolatedStringNode } from './types.js';
+/**
+ * Parses a sequence of tokens into an AST.
+ *
+ * @param tokens - The tokens to parse
+ * @returns The parsed AST (InterpolatedStringNode)
+ */
+export declare function parse(tokens: Token[]): InterpolatedStringNode;

package/dist/0.9/interpolation/parser.js

@@ -0,0 +1,236 @@
+/**
+ * Parser for string interpolation expressions.
+ *
+ * Converts a sequence of tokens into an Abstract Syntax Tree (AST).
+ * Implements a recursive descent parser for the LL(1) grammar.
+ */
+import { TokenType } from './types.js';
+/** Maximum nesting depth for expressions to prevent stack overflow */
+const MAX_DEPTH = 10;
+/**
+ * Parses a sequence of tokens into an AST.
+ *
+ * @param tokens - The tokens to parse
+ * @returns The parsed AST (InterpolatedStringNode)
+ */
+export function parse(tokens) {
+    const state = { tokens, pos: 0, depth: 0 };
+    return parseInterpolatedString(state);
+}
+/**
+ * Returns the current token without advancing.
+ */
+function peek(state) {
+    return (state.tokens[state.pos] || {
+        type: TokenType.EOF,
+        value: '',
+        start: 0,
+        end: 0,
+    });
+}
+/**
+ * Returns the current token and advances position.
+ */
+function advance(state) {
+    return (state.tokens[state.pos++] || {
+        type: TokenType.EOF,
+        value: '',
+        start: 0,
+        end: 0,
+    });
+}
+/**
+ * Parses the root interpolated string node.
+ */
+function parseInterpolatedString(state) {
+    const parts = [];
+    while (peek(state).type !== TokenType.EOF) {
+        const token = peek(state);
+        if (token.type === TokenType.TEXT) {
+            advance(state);
+            parts.push({ type: 'literal', value: token.value });
+        }
+        else if (token.type === TokenType.EXPR_START) {
+            advance(state); // consume ${
+            state.depth++;
+            if (state.depth > MAX_DEPTH) {
+                // Max depth exceeded - skip to closing }
+                console.warn('[A2UI] Parse error: Maximum nesting depth exceeded');
+                skipToExprEnd(state);
+                state.depth--;
+                continue;
+            }
+            const expr = parseExpression(state);
+            if (expr) {
+                parts.push(expr);
+            }
+            // Expect closing }
+            if (peek(state).type === TokenType.EXPR_END) {
+                advance(state);
+            }
+            state.depth--;
+        }
+        else if (token.type === TokenType.EXPR_END) {
+            // Unexpected } - might be from nested expression context
+            break;
+        }
+        else {
+            // Skip unknown tokens at top level
+            advance(state);
+        }
+    }
+    // If no parts, add empty literal
+    if (parts.length === 0) {
+        parts.push({ type: 'literal', value: '' });
+    }
+    return { type: 'interpolatedString', parts };
+}
+/**
+ * Parses a single expression inside ${...}.
+ */
+function parseExpression(state) {
+    const token = peek(state);
+    // Path expression (absolute)
+    if (token.type === TokenType.PATH) {
+        return parsePath(state);
+    }
+    // Function call or relative path
+    if (token.type === TokenType.IDENTIFIER) {
+        // Look ahead to see if it's a function call
+        const nextPos = state.pos + 1;
+        const nextToken = state.tokens[nextPos];
+        if (nextToken && nextToken.type === TokenType.LPAREN) {
+            return parseFunctionCall(state);
+        }
+        // It's actually a relative path (shouldn't happen if lexer is correct)
+        return parsePath(state);
+    }
+    // Nested expression
+    if (token.type === TokenType.EXPR_START) {
+        advance(state); // consume ${
+        state.depth++;
+        if (state.depth > MAX_DEPTH) {
+            console.warn('[A2UI] Parse error: Maximum nesting depth exceeded');
+            skipToExprEnd(state);
+            state.depth--;
+            return null;
+        }
+        const expr = parseExpression(state);
+        if (peek(state).type === TokenType.EXPR_END) {
+            advance(state);
+        }
+        state.depth--;
+        return expr;
+    }
+    // Literal value (inside function args)
+    if (token.type === TokenType.STRING ||
+        token.type === TokenType.NUMBER ||
+        token.type === TokenType.BOOLEAN) {
+        return parseLiteral(state);
+    }
+    // Empty or invalid expression
+    return null;
+}
+/**
+ * Parses a path node.
+ */
+function parsePath(state) {
+    const token = advance(state);
+    const absolute = token.value.startsWith('/');
+    return { type: 'path', path: token.value, absolute };
+}
+/**
+ * Parses a function call node.
+ */
+function parseFunctionCall(state) {
+    const nameToken = advance(state); // function name
+    advance(state); // consume (
+    const args = [];
+    // Parse arguments
+    while (peek(state).type !== TokenType.RPAREN &&
+        peek(state).type !== TokenType.EOF) {
+        const arg = parseArgument(state);
+        if (arg) {
+            args.push(arg);
+        }
+        // Skip comma between arguments
+        if (peek(state).type === TokenType.COMMA) {
+            advance(state);
+        }
+    }
+    // Consume closing )
+    if (peek(state).type === TokenType.RPAREN) {
+        advance(state);
+    }
+    return { type: 'functionCall', name: nameToken.value, args };
+}
+/**
+ * Parses a function argument.
+ */
+function parseArgument(state) {
+    const token = peek(state);
+    // Nested expression ${...}
+    if (token.type === TokenType.EXPR_START) {
+        advance(state); // consume ${
+        state.depth++;
+        if (state.depth > MAX_DEPTH) {
+            console.warn('[A2UI] Parse error: Maximum nesting depth exceeded');
+            skipToExprEnd(state);
+            state.depth--;
+            return null;
+        }
+        const expr = parseExpression(state);
+        if (peek(state).type === TokenType.EXPR_END) {
+            advance(state);
+        }
+        state.depth--;
+        return expr;
+    }
+    // Literal string
+    if (token.type === TokenType.STRING) {
+        return parseLiteral(state);
+    }
+    // Literal number
+    if (token.type === TokenType.NUMBER) {
+        return parseLiteral(state);
+    }
+    // Literal boolean
+    if (token.type === TokenType.BOOLEAN) {
+        return parseLiteral(state);
+    }
+    // Path (absolute)
+    if (token.type === TokenType.PATH) {
+        return parsePath(state);
+    }
+    // Identifier could be function call or relative path
+    if (token.type === TokenType.IDENTIFIER) {
+        const nextPos = state.pos + 1;
+        const nextToken = state.tokens[nextPos];
+        if (nextToken && nextToken.type === TokenType.LPAREN) {
+            return parseFunctionCall(state);
+        }
+    }
+    return null;
+}
+/**
+ * Parses a literal value node.
+ */
+function parseLiteral(state) {
+    const token = advance(state);
+    return { type: 'literal', value: token.value };
+}
+/**
+ * Skips tokens until expression end is found.
+ */
+function skipToExprEnd(state) {
+    let depth = 1;
+    while (depth > 0 && peek(state).type !== TokenType.EOF) {
+        const token = advance(state);
+        if (token.type === TokenType.EXPR_START) {
+            depth++;
+        }
+        else if (token.type === TokenType.EXPR_END) {
+            depth--;
+        }
+    }
+}

package/dist/0.9/interpolation/parser.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the parser.
+ */
+export {};