@xaendar/compiler 0.0.1

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@xaendar/compiler",
+  "version": "0.0.1",
+  "type": "module",
+  "author": "Kaitenjo",
+  "license": "MIT",
+  "description": "A library containing compiler engine",
+  "peerDependencies": {
+    "@xaendar/common": "1.0.0",
+    "vite": "^8.0.4"
+  }
+}

package/src/costants/chars.constants.ts

@@ -0,0 +1,188 @@
+/**
+ * `EOF`
+ */
+export const EOF = 0;
+/**
+ * `\b`
+ */
+export const BACK_SPACE = 8;
+/**
+ * `\t`
+ */
+export const TAB = 9;
+/**
+ * `\n`
+ */
+export const LF = 10;
+/**
+ * `\v`
+ */
+export const VERTICAL_TAB = 11;
+/**
+ * `\f`
+ */
+export const FF = 12;
+/**
+ * `\r`
+ */
+export const CR = 13;
+/**
+ * ` `
+ */
+export const SPACE = 32;
+/**
+ * `!`
+ */
+export const EXCLAMATION = 33;
+/**
+ * `'`
+ */
+export const DOUBLE_QUOTE = 34;
+/**
+ * `#`
+ */
+export const HASHTAG = 35;
+/**
+ * `$`
+ */
+export const DOLLAR = 36;
+/**
+ * `%`
+ */
+export const PERCENTAGE = 37;
+/**
+ * `&`
+ */
+export const AMPERSAND = 38;
+/**
+ * `'`
+ */
+export const SINGLE_QUOTE = 39;
+/**
+ * `(`
+ */
+export const LPAREN = 40;
+/**
+ * `)`
+ */
+export const RPAREN = 41;
+/**
+ * `*`
+ */
+export const STAR = 42;
+/**
+ * `+`
+ */
+export const PLUS = 43;
+/**
+ * `,`
+ */
+export const COMMA = 44;
+/**
+ * `-`
+ */
+export const MINUS = 45;
+/**
+ * `.`
+ */
+export const PERIOD = 46;
+/**
+ * `/`
+ */
+export const SLASH = 47;
+/**
+ * `0`
+ */
+export const ZERO = 48;
+/**
+ * `9`
+ */
+export const NINE = 57;
+/**
+ * `:`
+ */
+export const COLON = 58;
+/**
+ * `;`
+ */
+export const SEMICOLON = 59;
+/**
+ * `<`
+ */
+export const LESS_THAN = 60;
+/**
+ * `=`
+ */
+export const EQUAL_THEN = 61;
+/**
+ * `>`
+ */
+export const GREATER_THEN = 62;
+/**
+ * `?`
+ */
+export const QUESTION = 63;
+/**
+ * `@`
+ */
+export const AT_SIGN = 64;
+/**
+ * `A`
+ */
+export const A = 65;
+/**
+ * `Z`
+ */
+export const Z = 90;
+/**
+ * `[`
+ */
+export const LEFT_BRACKET = 91;
+/**
+ * `\`
+ */
+export const BACKSLASH = 92;
+/**
+ * `]`
+ */
+export const RIGHT_BRACKET = 93;
+/**
+ * `^`
+ */
+export const CARET = 94;
+/**
+ * `_`
+ */
+export const UNDERSCORE = 95;
+/**
+ * ```
+ */
+export const GRAVE_ACCENT = 96;
+/**
+ * `a`
+ */
+export const a = 97;
+/**
+ * `z`
+ */
+export const z = 122;
+/**
+ * `{`
+ */
+export const LEFT_BRACE = 123;
+/**
+ * `|`
+ */
+export const VERTICAL_BAR = 124;
+/**
+ * `}`
+ */
+export const RIGHT_BRACE = 125;
+/**
+ * `~`
+ */
+export const TILDE = 126;
+/**
+ * `NBSP`
+ */
+export const NBSP = 160;

package/src/costants/tags/base-tags.constants.ts

@@ -0,0 +1,106 @@
+/**
+ * List of all standard, valid HTML tags in Xendar Components's Template
+ * 
+ * These are native HTML elements and should not be used as custom element names.
+ */
+export const HTML_TAGS = [
+  'section',
+  'article',
+  'aside',
+  'nav',
+  'header',
+  'footer',
+  'address',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'p',
+  'hr',
+  'pre',
+  'blockquote',
+  'ol',
+  'ul',
+  'li',
+  'dl',
+  'dt',
+  'dd',
+  'figure',
+  'figcaption',
+  'div',
+  'a',
+  'span',
+  'br',
+  'wbr',
+  'b',
+  'strong',
+  'i',
+  'em',
+  'u',
+  's',
+  'mark',
+  'small',
+  'sub',
+  'sup',
+  'abbr',
+  'cite',
+  'code',
+  'var',
+  'kbd',
+  'samp',
+  'time',
+  'data',
+  'dfn',
+  'q',
+  'ruby',
+  'rt',
+  'rp',
+  'bdi',
+  'bdo',
+  'ins',
+  'del',
+  'img',
+  'iframe',
+  'embed',
+  'object',
+  'param',
+  'picture',
+  'source',
+  'track',
+  'video',
+  'audio',
+  'map',
+  'area',
+  'table',
+  'caption',
+  'colgroup',
+  'col',
+  'tbody',
+  'thead',
+  'tfoot',
+  'tr',
+  'td',
+  'th',
+  'form',
+  'label',
+  'input',
+  'button',
+  'select',
+  'datalist',
+  'optgroup',
+  'option',
+  'textarea',
+  'output',
+  'progress',
+  'meter',
+  'fieldset',
+  'legend',
+  'details',
+  'summary',
+  'dialog',
+  'template',
+  'slot',
+  'canvas'
+];

package/src/costants/tags/not-alllowed-tags.constants.ts

@@ -0,0 +1,13 @@
+/**
+ * List of strings not allowed as names for CustomElements
+ */
+export const NOT_ALLOWED_TAGS = [
+  'annotation-xml',
+  'color-profile',
+  'font-face',
+  'font-face-src',
+  'font-face-uri',
+  'font-face-format',
+  'font-face-name',
+  'missing-glyph'
+]

package/src/costants/tags/not-allowed-chars.constants.ts

@@ -0,0 +1,24 @@
+/**
+ * List of characters that are not allowed in a custom element tag name.
+ * 
+ * These characters are forbidden according to the Custom Elements specification
+ * and will make a tag name invalid if included.
+ */
+export const NOT_ALLOWED_CHARS_FOR_TAGS = [
+  '@',
+  '#',
+  '$',
+  '%',
+  '&',
+  '*',
+  '!',
+  '?',
+  '/',
+  '\\',
+  '|',
+  "'",
+  '"',
+  '<',
+  '>',
+  '='
+];

package/src/lexer/lexer.ts

@@ -0,0 +1,91 @@
+import { Dictionary, Stack } from '@xaendar/common';
+import { EOF } from '../costants/chars.constants';
+import { LexerCursor } from './models/lexer-cursor.model';
+import { LexerState } from './models/lexer-state.enum';
+import { Token } from './models/token.type';
+import { LexerTransitionFunction } from './models/transition-function/transition-function.type';
+import { consumeAttribute } from './states/attribute.state';
+import { consumeEvent } from './states/event.state';
+import { consumeInterpolationExpression } from './states/interpolation-expression.state';
+import { consumeInterpolationliteral } from './states/interpolation-literal.state';
+import { consumeInterpolation } from './states/interpolation.state';
+import { consumeTagBody } from './states/tag-body.state';
+import { consumeTagClose } from './states/tag-close.state';
+import { consumeTagOpenEnd } from './states/tag-open-end.state';
+import { consumeTagOpenName } from './states/tag-open-name.state';
+import { consumeText } from './states/text.state';
+
+/**
+ * Utility class that emulates a cursor navigating through a template string.
+ *
+ * The cursor keeps track of the current character, its absolute position
+ * within the text, and its logical position expressed as row and column.
+ * This is useful when parsing or analyzing template content character by character.
+ */
+export class Lexer {
+
+  private readonly _cursor;
+
+  private _state = LexerState.START;
+
+  private _stack = new Stack<LexerState>;
+
+  private readonly _tokens = new Array<Token>;
+
+  private readonly _states: Dictionary<LexerState, LexerTransitionFunction> = {
+    [LexerState.START]: consumeText,
+    [LexerState.TEXT]: consumeText,
+    [LexerState.TAG_OPEN_NAME]: consumeTagOpenName,
+    [LexerState.TAG_BODY]: consumeTagBody,
+    [LexerState.TAG_OPEN_END]: consumeTagOpenEnd,
+    [LexerState.TAG_CLOSE]: consumeTagClose,
+    [LexerState.ATTRIBUTE]: consumeAttribute,
+    [LexerState.EVENT]: consumeEvent,
+    [LexerState.INTERPOLATION]: consumeInterpolation,
+    [LexerState.INTERPOLATION_EXPRESSION]: consumeInterpolationExpression,
+    [LexerState.INTERPOLATION_LITERAL]: consumeInterpolationliteral
+  }
+
+  /**
+   * Creates a new Cursor instance for the given template content.
+   *
+   * @param input The full template text that the cursor will navigate.
+   */
+  constructor(public input: string) {
+    this._cursor = new LexerCursor(this.input);
+  }
+
+  public tokenize(): Token[] {
+    let eof = false;
+
+    while (!eof) {
+      try {
+        const transitionFunction = this._states[this._state];
+        const { state, tokens, popState, pushState } = transitionFunction!(this._cursor, { history: this._stack.values });
+        
+        if (tokens?.length) {
+          this._tokens.push(...tokens);
+        }
+        
+        if (pushState) {
+          this._stack.push(this._state);
+        }
+        
+        if (popState) {
+          this._stack.pop();
+        } 
+        
+        this._state = state;
+      } catch (err) {
+        const error = err as Error;
+        if (error.cause === EOF) {
+          eof = true;
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    return this._tokens;
+  }
+}

package/src/lexer/models/current-char.type.ts

@@ -0,0 +1,17 @@
+/**
+ * Represents a character within a string during parsing.
+ */
+export type CurrentChar = {
+  /**
+   * Index of the character in the original string.
+   */
+  index: number
+  /**
+   * UTF-16 code unit of the character (from String.charCodeAt).
+   */
+  code: number
+  /**
+   * String value of the character.
+   */
+  value: string
+}

package/src/lexer/models/current-position.type.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents a cursor position in a text document.
+ */
+export type CursorPosition = {
+  /**
+   * Zero-based row index.
+   */
+  row: number
+  /**
+   * Zero-based column index.
+   */
+  column: number
+}

package/src/lexer/models/lexer-cursor.model.ts

@@ -0,0 +1,192 @@
+import { PositiveInteger, TupleOfLength } from '@xaendar/common';
+import { CR, EOF, LF, SPACE } from '../../costants/chars.constants';
+import { CurrentChar } from './current-char.type';
+import { CursorPosition } from './current-position.type';
+
+/**
+ * Cursor abstraction used by the Lexer to navigate the input source.
+ *
+ * The LexerCursor is responsible for:
+ * - Sequential character consumption
+ * - Lookahead (peek) operations without state mutation
+ * - Tracking logical position (row, column)
+ * - Handling end-of-file conditions
+ *
+ * This class deliberately contains **no lexer logic**:
+ * it does not know about tokens, states, or grammar rules.
+ * Its sole responsibility is controlled navigation of the input stream.
+ */
+export class LexerCursor {
+  /**
+   * Representation of the current character.
+   *
+   * - `index`: absolute index within the input string
+   * - `code`: Unicode code point of the character
+   * - `value`: actual character value
+   *
+   * An index of `-1` indicates that the cursor has not yet consumed
+   * any character or has reached EOF.
+   */
+  private readonly _currentChar: CurrentChar = {
+    code: 0,
+    index: -1,
+    value: ''
+  };
+  /**
+   * Returns a read-only snapshot of the current character.
+   */
+  public get currentChar(): Readonly<CurrentChar> {
+    return this._currentChar;
+  }
+  /**
+   * Cache used by peek operations to avoid re-reading
+   * the same character positions multiple times.
+   *
+   * Key: absolute character index
+   * Value: Unicode code point
+   */
+  private readonly _peekCache = new Map<number, number>();
+  /**
+   * Logical position of the cursor in the input.
+   *
+   * - `row`: zero-based line number
+   * - `column`: zero-based column number
+   */
+  private readonly _position: CursorPosition = {
+    row: 0,
+    column: 0
+  };
+  /**
+   * Returns a read-only snapshot of the current cursor position.
+   */
+  public get position(): Readonly<CursorPosition> {
+    return this._position;
+  }
+  /**
+   * Creates a new cursor for the given input source.
+   *
+   * @param input Full source string to be tokenized.
+   */
+  constructor(public input: string) { }
+
+  /**
+   * Advances the cursor by the specified number of characters.
+   *
+   * This method:
+   * - Updates the current character
+   * - Updates row/column position
+   * - Detects line breaks (LF / CR)
+   * - Throws an EOF error when the end of the input is reached
+   *
+   * @param chars Number of characters to consume (must be >= 1)
+   *
+   * @throws Error with cause `EOF` when advancing past input length
+   */
+  public advance(chars = 1): void {
+    if (chars < 1) {
+      throw new Error(`${chars} is not a valid value. Please enter a number equal or greater than 1`);
+    }
+
+    const newIndex = this._currentChar.index + chars;
+
+    if (newIndex >= this.input.length) {
+      this._currentChar.code = EOF;
+      this._currentChar.index = -1;
+      this._currentChar.value = '';
+      this.throwEOFError();
+    } else {
+      /*
+        Before updating the character, adjust logical position.
+        Line breaks reset column and increment row.
+      */
+      if ([LF, CR].includes(this._currentChar.code)) {
+        this._position.row++;
+        this._position.column = 0;
+      } else {
+        this._position.column++;
+      }
+
+      this._currentChar.index = newIndex;
+      this._currentChar.value = this.input[newIndex]!;
+      this._currentChar.code = this.input.charCodeAt(newIndex);
+    }
+  }
+
+  /**
+   * Peeks ahead in the input stream without advancing the cursor.
+   *
+   * This method supports:
+   * - Single-character lookahead
+   * - Multi-character lookahead
+   * - Optional offset from the current position
+   *
+   * Peek operations are cached for performance reasons and do not
+   * modify the cursor state.
+   *
+   * @returns
+   * - A single Unicode code point when peeking one character
+   * - An array of Unicode code points when peeking multiple characters
+   *
+   * @throws Error with cause `EOF` if the peek exceeds input length
+   */
+  public peek(): number;
+  public peek<OffSet extends number>(options?: { offset?: PositiveInteger<OffSet> }): number;
+  public peek(chars: 1): number;
+  public peek<OffSet extends number>(chars: 1, options?: { offset?: PositiveInteger<OffSet> }): number; 
+  public peek<ReadChars extends number>(chars: PositiveInteger<ReadChars>): TupleOfLength<ReadChars>; 
+  public peek<ReadChars extends number, OffSet extends number>(chars: PositiveInteger<ReadChars>, options?: { offset?: PositiveInteger<OffSet> }): TupleOfLength<ReadChars>;
+  public peek(charsOrOptions?: number | { offset?: number }, options?: { offset?: number }): number | number[] {
+    const cache = this._peekCache;
+    const chars = typeof charsOrOptions === 'number' ? charsOrOptions : 1;
+    const offset = (typeof charsOrOptions === 'object' ? charsOrOptions : options)?.offset ?? 0;
+    return chars === 1 ? this.peekOneChar(this._currentChar.index + offset + 1, cache) : this.peekMany(chars + offset, cache);
+  }
+
+  /**
+   * Skips all consecutive space characters from the current position.
+   */
+  public skipSpaces(): void {
+    while (this.peek() === SPACE) {
+      this.advance();
+    }
+  }
+
+  /**
+   * Peeks multiple characters ahead.
+   */
+  private peekMany(chars: number, cache: Map<number, number>): number[] {
+    const peekedChars: number[] = [];
+    const nextCharIndex = this._currentChar.index + 1;
+
+    for (let i = nextCharIndex; i < nextCharIndex + chars; i++) {
+      peekedChars.push(this.peekOneChar(i, cache));
+    }
+
+    return peekedChars;
+  }
+
+  /**
+   * Peeks a single character at the given absolute index.
+   */
+  private peekOneChar(index: number, cache: Map<number, number>): number {
+    if (cache.has(index)) {
+      return cache.get(index)!;
+    }
+
+    if (index >= this.input.length) {
+      this.throwEOFError();
+    }
+
+    const charCode = this.input.charCodeAt(index);
+    cache.set(index, charCode);
+    return charCode;
+  }
+
+  /**
+   * Throws a standardized EOF error used by the lexer engine
+   * to terminate tokenization.
+   */
+  private throwEOFError(): never {
+    throw new Error('', { cause: EOF });
+  }
+}

package/src/lexer/models/lexer-state.enum.ts

@@ -0,0 +1,13 @@
+export enum LexerState {
+  START = 'start',           
+  TEXT = 'text',
+  TAG_OPEN_NAME = 'tag-open-name',
+  TAG_BODY  = 'tag-body',
+  TAG_OPEN_END = 'tag-open-end',
+  TAG_CLOSE = 'tag-close',
+  ATTRIBUTE = 'attribute',
+  EVENT = 'event',   
+  INTERPOLATION = 'interpolation',
+  INTERPOLATION_EXPRESSION = 'interpolation-expression',
+  INTERPOLATION_LITERAL = 'interpolation-literal'
+}

package/src/lexer/models/token-type.enum.ts

@@ -0,0 +1,17 @@
+export enum TokenType {
+  TEXT,
+
+  TAG_OPEN_NAME,      // <div
+  TAG_SELF_CLOSE,     // />
+  TAG_OPEN_END,
+
+  TAG_CLOSE_NAME,     // </div
+
+  ATTRIBUTE,
+  EVENT,
+
+  INTERPOLATION_LITERAL,
+  INTERPOLATION_EXPRESSION,
+
+  EOF
+}